Overview

Getting started

This page takes you from nothing to your first answer out of a namespace. It assumes you have an AI host — codex, Claude Code, or Antigravity — and a namespace route. If you just want to try it, the public worked example is:

https://theorymcp.ai/theorycloud/mcp

Step 1 — Point your host at the route

The MCP server id is theorymcp in every host. Pick yours; the full matrix is on Connect a host.

codex — in .codex/config.toml:

[mcp_servers.theorymcp]
url            = "https://theorymcp.ai/theorycloud/mcp"
oauth_resource = "https://theorymcp.ai/theorycloud/mcp"
scopes         = ["mcp:tools", "ai.kb.query"]

Claude Code — in the repo-root .mcp.json:

{
  "mcpServers": {
    "theorymcp": { "type": "http", "url": "https://theorymcp.ai/theorycloud/mcp" }
  }
}

Antigravity — in .agents/mcp_config.json, through the bridge:

{
  "mcpServers": {
    "theorymcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://theorymcp.ai/theorycloud/mcp"] }
  }
}

Step 2 — Authenticate

  • codex: codex mcp login theorymcp (the configured server name) — completes browser OAuth natively.
  • Claude Code: open /mcp, choose theorymcp, authenticate in the browser.
  • Antigravity: the first connection opens a browser once; the mcp-remote bridge holds the token afterward.

One route, one authorization

OAuth is route-scoped. The token you mint for …/theorycloud/mcp authorizes that route only. If you later connect an agent endpoint like …/agents/apptheory/mcp, that is a distinct authorization.

Step 3 — Ground before you act

Never assume a namespace’s tools. Paste this into your host:

Ground me in the namespace at https://theorymcp.ai/theorycloud/mcp.
Call describe_interface and summarize the available tools, the visible knowledge bases,
whether agent installs are available, and the route-derived identity. Use only the tool
names describe_interface returns.

You’ll get back the real tool surface for this route, the knowledge bases you can search, and your resolved client_namespace / endpoint_kind.

Step 4 — Ask the namespace something

Now query its knowledge. The pattern is search first (previews), then fetch detail:

In the theorycloud namespace, list the knowledge bases, then search the most relevant one
for "<your question>". Show me the top results as previews (title + summary + relevance),
then call get_unit on the best match and answer my question from its authoritative body.
Cite the unit_id you used.

That’s the whole loop: connect → authenticate → ground → query.

Production self-serve — connect and operate without opening a cloud console
The self-serve posture: you connect to a route and operate against it. No console, no per-capability account — the platform resolves entitlements server-side.

What next?