# MCP server Use hosted, read-only agent tools > Section: Integrations > Last updated: **2026-10-24**. > API version: **v1 (Latest)**. OpenAPI publication: **2026-10-05**. ## Connect OAuth capable clients use one public endpoint and browser sign in. Open registration remains fail closed until the public admission gate passes. ```text https://beliefstate.ai/mcp ``` - [Choose your AI client and follow setup](https://beliefstate.ai/connect) ## How it works The client discovers authorization metadata, the user signs in on BeliefState, and the approved client receives a revocable read only grant. Search with `search_beliefs` using a thesis, topic or trade setup. Open returned IDs with `get_belief`; compare two cases with `compare_beliefs`. Your AI chooses the tool. No mode selector is required. | Tool | Purpose | | --- | --- | | `search_beliefs` | Find investment ideas by thesis, topic or trade setup, with cited matching passages. | | `get_belief` | Read a requested complete investment case or evidence beyond a brief, with risks, conditions and coverage gaps. An ordinary library overview can use get_brief without opening each case. Use paragraph_index only when it appears in the returned investment_case; follow support/text offsets. Records without investment_case return their full claims and citations without paragraph selectors. | | `compare_beliefs` | Compare two cited investment cases for support, contradiction or dependency, including explicit unknown and unrelated outcomes. Optional comparison_focus selects a public research topic within both complete cases; the result applies to that topic only. Shared-source provenance does not establish research independence. | | `get_brief` | Answer ordinary company, ETF or subject research questions in one brief per requested subject. ETF briefs join dated holdings with company research, weights and coverage limits. Stock overviews include selected cited views, dated outlook and changes when available. Answer from the returned evidence; more calls are for requested depth or specific unanswered questions. Oversized full MCP reads return a labeled overview. Missing/stale requested inputs refresh within bounds; historical reads preserve their cutoff. | | `get_beliefs` | List dated investment ideas for a requested inventory or filtered research on one ticker or subject. Investor, direction and time filters are optional. An ordinary overview uses get_brief; listing the same research afterward is unnecessary unless the user needs additional cases. | | `get_tickers` | List direct company research coverage and counts. ETF holdings coverage is available through get_brief even when the ETF is absent from this company list. Free. | | `search_entities` | Find released companies, industries, themes and other research subjects by name or kind. | | `get_belief_changes` | Read a mixed, ordered change journal: author-view revisions, distribution changes and calculated publication outcomes are separate domains with distinct clocks. Use belief_id for changes to one case and inspect each event's domain. Use get_brief for a current synthesis; continuation is for requested journal history or polling. | | `get_context_assessment` | Open a dated engine context assessment and its permitted evidence. Engine analysis is separate from an investor's stated view. | | `list_research_visuals` | List cited charts and tables for one investment case or context assessment. | | `get_research_visual` | Read one cited chart or table, including its regions and paginated exact rows or data points. | | `get_belief_relationships` | Inspect cited relationship paths within one investment case. Preserves stated links, engine inferences and unknowns. | | `evaluate_belief_scenario` | Apply up to eight hypothetical condition assumptions to a case's recorded scenario model. Does not alter evidence or predict the investor's response. | | `refresh_market_data` | Explicitly refresh missing or stale market data for one current company or subject, then return its research brief. | | `search_companies` | Search the SEC-registered US company directory by ticker or name and check direct research availability. Free. | | `get_tracked_tickers` | Read the connected account's actively tracked tickers. Free. | - No BeliefState SDK is required. - All admitted clients use the same remote Streamable HTTP endpoint. - MCP tools use the same read services, release gates, pricing policy, and append only usage ledger as REST. - Client compatibility and provider approval are verified separately. ## Verify The agent verifies its own response: requested ticker, data mode, coverage warnings, and citations. Report missing access or coverage as a blocked step; a configured server alone does not prove a useful result. ```text Verify BeliefState using the company from my question. Check released coverage, discover available tools, and call get_brief with that company's ticker. If this is only a connection test and no company was requested, select a ticker from current coverage and label it as a test. Return the actual ticker, data_status.mode, warnings, citations, and explicit unknowns. Report missing coverage or access without substituting another company or claiming setup succeeded. ``` ## Documentation for agents Give your coding agent current API references and integration guides without an API key or sign in. Add this public documentation endpoint to an MCP compatible client. ```text https://beliefstate.ai/docs/mcp ``` - `search_docs` (Read only). Search current BeliefState guides and API references. Returns ranked pages with short excerpts. - `read_docs` (Read only). Read current docs as Markdown: supply path and optional section (heading or anchor), or pages for up to 8 reads in one call. Search anchors also work as URL fragments. Unknown selections return per-page errors. Responses are bounded to 120,000 characters; request sections for larger batches. - `submit_docs_feedback` (Records feedback). Report whether one documentation page was useful, with an optional concise correction or missing detail. Your client can also read every public documentation page and the published agent skills as Markdown resources. The documentation server provides no analyst records. Use account-based /mcp or an x402-capable wallet client at /v1/research/mcp for analyst queries. Check /v1/research for current per-tool prices and schemas. - [View documentation tool schemas](https://beliefstate.ai/.well-known/mcp/docs-server-card.json) ## Automatic discovery Find documentation, account-based research and wallet-paid research MCP endpoints from one public discovery document, with their authentication or payment requirements. ```bash curl --fail-with-body "https://beliefstate.ai/.well-known/mcp" ``` The discovery document defaults to public documentation and lists account-based intelligence with OAuth plus accountless /v1/research/mcp with x402 wallet payments. It is also available at [/.well-known/mcp.json](https://beliefstate.ai/.well-known/mcp.json). The documentation card includes tool descriptions, input schemas, bounds, and read/write annotations from the running server's definitions. Discovery does not grant access or change client admission requirements. - [View MCP discovery](https://beliefstate.ai/.well-known/mcp) - [View server cards](https://beliefstate.ai/.well-known/mcp/server-cards.json) - [View x402 tool prices and schemas](https://beliefstate.ai/v1/research) ## Security Leave passwords, consent, workspace selection, and provider admin approval with the user. > An AI must never ask for the user's password, session, OAuth access token, or developer API key. ## Agent feedback Report unclear, stale, or incorrect documentation through [BeliefState support](https://beliefstate.ai/contact). Include this page URL and the smallest reproducible detail.