Remote MCP

Local editor tools spawn the MCP server on your machine. Hosted agents can't do that — so SecondOS also serves a remote endpoint you connect to with a project-scoped token. Same map and memory, over HTTP.

Local vs remote

Two ways to reach the same twenty-two tools, depending on where the agent runs:

• Local (stdio) — for tools that run on your machine and can start a process: Cursor, Claude Code, Claude Desktop, Windsurf, VS Code. Run bunx @secondos/cli mcp-config and paste the printed config. No token — it reads your local, synced project.
• Remote (hosted) — for agents that run in the cloud and can't spawn a process: a claude.ai custom connector, ChatGPT, or any MCP-over-HTTP client. They connect to the hosted /mcp endpoint with a Bearer token.

Create a token

Remote tokens are per project. Open a project, go to Integrations, and find Remote MCP — connect a hosted agent. Give the token a label (for example the agent it's for), then Create token.

The token is shown once. Copy it right then — it's never displayed again, the same way a CLI token or a webhook secret is. If you lose it, revoke it and create a new one.

Add it as a custom connector

The Integrations panel shows the endpoint URL and a ready-to-paste connector config. In your hosted agent, add a custom MCP connector of type Streamable HTTP with:

• URL — the endpoint shown in the panel, e.g. https://secondos.app/mcp.
• Authorization header — Authorization: Bearer <token>.

{
  "mcpServers": {
    "secondos": {
      "url": "https://secondos.app/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Once connected, the agent can call the same codebase, memory and context tools as any local tool — scoped to the one project the token belongs to.

Scope & least privilege

A remote token is bound to a single project and carries only the read and memory tools — search the map, trace impact, remember and recall. It can't touch your account, your billing, other projects, or your source (the source was never uploaded). Revoke a token any time from the same panel; the agent using it loses access immediately.

Next

See the MCP server for the full tool surface, the CLI reference for local setup, or security for the trust boundary.