# BeliefState agent quickstart Connect any MCP-capable AI agent to BeliefState as a remote, read-only server. No BeliefState SDK is required. ## Choose the connection path For ChatGPT, Claude, or any OAuth-capable MCP client, use the retail guide at https://beliefstate.ai/agents: - Name: BeliefState - Remote MCP URL: https://beliefstate.ai/mcp - Transport: Streamable HTTP - Authentication: OAuth or browser sign-in The user completes BeliefState sign-in and consent. The AI must never ask for the user's password, session, OAuth token, or API key. Setup is provider-neutral: every compatible provider uses the same MCP URL and receives the same read-only tools. Use the API-key path below only for a trusted technical integration that cannot complete OAuth. It is separate from retail chat setup. ## Endpoints - REST base URL: https://beliefstate.ai/v1 - Remote MCP server: https://beliefstate.ai/mcp - Belief changes: https://beliefstate.ai/v1/belief-changes - Authentication setup: https://beliefstate.ai/auth.md - Discovery document: https://beliefstate.ai/llms.txt For developer API-key integrations, send the key on every REST or MCP request: ```http Authorization: Bearer ``` Keep the key server-side. Never expose it in browser code, logs, commits, or chat. For paid REST operations, send a stable bounded `X-Request-ID` and reuse it only when retrying the same logical request. BeliefState uses that ID for exactly-once reservation and finalization. MCP clients receive equivalent request scoping from the transport session. ## 1. Configure the MCP client ### OAuth-capable chat and agent clients Add https://beliefstate.ai/mcp as a remote Streamable HTTP MCP server and choose OAuth or browser sign-in. The client should discover authorization metadata automatically. Follow the human-visible provider steps at https://beliefstate.ai/agents and verify with a real NBIS call. ### Developer clients using API keys Use these values only in a trusted client that cannot complete OAuth: - Name: beliefstate - URL: https://beliefstate.ai/mcp - Authorization: Bearer token from BELIEFSTATE_API_KEY Store the key in the client's secret store or process environment. Do not put the key itself in a committed configuration file. ### Codex Check whether a beliefstate server already exists: ```bash codex mcp get beliefstate ``` If it does not exist, add it: ```bash codex mcp add beliefstate \ --url https://beliefstate.ai/mcp \ --bearer-token-env-var BELIEFSTATE_API_KEY ``` This stores the environment-variable name, not the API key. If an existing beliefstate entry has a different URL or authentication setting, explain the mismatch and ask before replacing it. Codex CLI, the IDE extension, and the desktop app share MCP configuration on the same computer. The command writes the global configuration at ~/.codex/config.toml. For project-only setup, add this definition to a trusted project's .codex/config.toml instead: ```toml [mcp_servers.beliefstate] url = "https://beliefstate.ai/mcp" bearer_token_env_var = "BELIEFSTATE_API_KEY" ``` Make BELIEFSTATE_API_KEY available to the environment that launches Codex, then start a new Codex session. ### Other developer MCP clients Add https://beliefstate.ai/mcp as a remote Streamable HTTP server. Supply `Authorization: Bearer ` through the client's secure header or secret configuration. If the client cannot connect to remote HTTP MCP servers, use the REST examples below. ## 2. Verify access Confirm that the client lists the beliefstate server. Codex users can run `codex mcp list`. Then verify the key and workspace over REST: ```bash curl --fail-with-body \ --header "Authorization: Bearer $BELIEFSTATE_API_KEY" \ "https://beliefstate.ai/v1/status" ``` A successful response includes the authenticated workspace, access state, and current usage. A valid key can exist before the workspace has paid access; intelligence queries require either an active subscription or positive prepaid credit. Finally, ask the connected agent to make a real tool call: ```text Use BeliefState get_belief_changes for NBIS since 2026-07-13T00:00:00.000Z. Return data_status.mode, warnings, citations, prior and current direction, and every explicit unknown. ``` Setup is complete only when the tool returns a structured response. A server shown in a client is configured, not yet proven authenticated. ## 3. Query a security timeline over REST ```bash curl --fail-with-body --get \ --header "Authorization: Bearer $BELIEFSTATE_API_KEY" \ --data-urlencode "ticker=NBIS" \ --data-urlencode "since=2026-07-13T00:00:00.000Z" \ "https://beliefstate.ai/v1/security-timeline" ``` The response returns paginated belief and position events with field provenance, as-of-safe outcomes, citations, warnings, and methodology versions. Market bars are omitted unless include_market_bars is true. Reuse the returned as_of while following pagination so later observations cannot leak into the result. ## 4. Query tracked-source consensus over REST ```bash curl --fail-with-body --get \ --header "Authorization: Bearer $BELIEFSTATE_API_KEY" \ --data-urlencode "ticker=NBIS" \ --data-urlencode "lookback_days=90" \ "https://beliefstate.ai/v1/security-consensus" ``` The response counts one latest recent directional belief per tracked public person. It is not market-wide consensus. Preserve scope, limitations, eligible_person_count, and penetration_percent. Fewer than two people produces label=insufficient; do not upgrade that result into a consensus claim. ## 5. Integrate another client Prefer a thin server-side adapter that reads BELIEFSTATE_API_KEY at request time, sets the Authorization header, preserves the full response metadata, and surfaces non-2xx response bodies. Do not discard citations, warnings, data_status, as_of, or methodology_versions. For MCP clients, configure https://beliefstate.ai/mcp as a remote HTTP server and supply the same Bearer header through the client's secure secret configuration. Use get_security_timeline for source history and get_security_consensus for scoped directional agreement. ## Builder preview mode Before live corpus coverage is ready, BeliefState builders can enable the fixture-only preview path on a local or isolated preview deployment: ```dotenv BELIEFSTATE_API_PREVIEW_ENABLED=true BELIEFSTATE_PREVIEW_API_KEY= BELIEFSTATE_API_KEY= BELIEFSTATE_APP_URL=http://localhost:3000 ``` Start BeliefState, then run `bun run beliefstate:smoke`. The command verifies authenticated REST status, belief changes, timeline, consensus, all three released MCP tools, and REST/MCP parity. Preview responses always set `data_status.mode` to `preview` and include a synthetic-data warning. Never enable this path with a reusable production credential. ## Security and lifecycle - Scope: read-only intelligence access. - Secret display: once, to the polling installer. - Revocation: https://beliefstate.ai/account#api-keys. - Funding: https://beliefstate.ai/subscribe. - Support: use response request IDs when reporting an error.