> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beliefstate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> We read investment research and turn each author’s ideas, reasoning, and risks into knowledge your AI can use.

BeliefState brings investor ideas to your AI.

BeliefState is a read-only intelligence API for researching what investors believed, when they believed it, and what evidence supported each view. Query it through MCP or REST.

## Get started

### Configure a coding client with an API key

You can also use an API key with an HTTP MCP client. [Create a key](https://beliefstate.ai/account#api-keys), then set `BELIEFSTATE_API_KEY` in the client's environment.

<Tabs>
  <Tab title="Codex" icon="https://beliefstate.ai/agents/codex-logo.svg">
    Run in your terminal:

    ```bash theme={null}
    codex mcp add beliefstate --url https://beliefstate.ai/mcp \
      --bearer-token-env-var BELIEFSTATE_API_KEY
    ```

    Open Codex's MCP tools and confirm `get_brief`, `get_beliefs`, and `get_tickers` appear.
  </Tab>

  <Tab title="Claude Code" icon="https://beliefstate.ai/agents/claude-logo.svg">
    Run in your project:

    ```bash theme={null}
    claude mcp add --transport http --scope project beliefstate \
      https://beliefstate.ai/mcp \
      --header 'Authorization: Bearer ${BELIEFSTATE_API_KEY}'
    ```

    Claude Code saves the variable name in `.mcp.json` and reads the key from its environment.
  </Tab>

  <Tab title="Cursor" icon="https://beliefstate.ai/agents/cursor-logo.svg">
    Add this server to `.cursor/mcp.json`. Keep any existing servers in the same `mcpServers` object.

    ```json theme={null}
    {
      "mcpServers": {
        "beliefstate": {
          "url": "https://beliefstate.ai/mcp",
          "headers": {
            "Authorization": "Bearer ${env:BELIEFSTATE_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="OpenCode" icon="https://opencode.ai/favicon.svg">
    Add this server to `opencode.json`. Keep any existing servers in the same `mcp` object.

    ```json theme={null}
    {
      "mcp": {
        "beliefstate": {
          "type": "remote",
          "url": "https://beliefstate.ai/mcp",
          "enabled": true,
          "oauth": false,
          "headers": {
            "Authorization": "Bearer {env:BELIEFSTATE_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Using another HTTP MCP client with an API key? Point it at `https://beliefstate.ai/mcp` and send the key as a Bearer token. [See the full MCP guide](/guides/mcp-server).

### Other ways to connect

Choose how you want to connect.

<CardGroup cols={3}>
  <Card title="Connect an AI" icon="robot" href="/guides/mcp-server" cta="Connect an AI" arrow>
    Sign in from a supported AI client to query released research.
  </Card>

  <Card title="Use REST" icon="code" href="/quickstart" cta="Read quickstart" arrow>
    Make a request from trusted code with a Bearer key.
  </Card>

  <Card title="Check coverage" icon="magnifying-glass" href="/concepts/coverage" cta="View coverage" arrow>
    See released tickers and coverage limits before you query.
  </Card>
</CardGroup>

[Check client availability](https://beliefstate.ai/connect) for ChatGPT and Claude. Public directory listings are not available yet; existing connections may still work.

### Build directly with the API

Check released ticker coverage without an API key:

```bash theme={null}
curl --fail-with-body "https://beliefstate.ai/v1/tickers"
```

[Continue to the REST quickstart](/quickstart) for authenticated requests and response handling.

## Explore the API

<CardGroup cols={2}>
  <Card title="API reference" icon="book" href="/api-reference/beliefs/find-investor-beliefs-or-inspect-a-full-record">
    Review released endpoints, parameters, and response fields.
  </Card>

  <Card title="OpenAPI spec" icon="file-code" href="/guides/openapi">
    Generate types or a client from the published contract.
  </Card>
</CardGroup>

## What can BeliefState do?

### Inspect a belief

Read an investor's thesis, confidence when known, catalysts, risks, invalidations, and cited evidence. [Review the belief endpoints](/api-reference/beliefs/find-investor-beliefs-or-inspect-a-full-record).

### Track revisions and outcomes

Compare belief changes over time and inspect outcomes where the underlying record supports them. Observation time and publication time remain distinct. [Learn about point-in-time queries](/guides/point-in-time).

### Check coverage and provenance

Research-source profiles describe coverage and eligibility. Derived sources do not prove the investor's exact wording or original publication. [Read the provenance guide](/concepts/provenance) and [coverage guide](/concepts/coverage).

## Resources

Keep citations, warnings, data mode, pagination, explicit unknowns, and methodology versions with downstream results. REST API version: **v1**. [See API versioning](/reference/versioning), [the changelog](/reference/changelog), or [contact support](https://beliefstate.ai/contact).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.