Connect External Agents

Your messy thinking lives in BuildOS. Your AI tools — Claude Code, OpenClaw, Codex, ChatGPT Actions, custom HTTP clients, and browser-based remote connectors — can read off the same sheet of paper instead of starting from zero each session.

Generate a key, or approve an OAuth grant from a remote MCP client. Choose where you are installing it. BuildOS gives you the right storage instructions for that client. Local tools usually use an MCP config, env var, or local stdio bridge. Private ChatGPT Actions use the Action authentication secret. Browser/cloud clients should use remote MCP with OAuth.

Per-project scope. Per-op write whitelist. Audit log. Rotate or revoke any time. No retraining your agents on your context every session.

What agents should do first

BuildOS is usually a workspace with many projects. After an agent connects, it should:

1. If using MCP, initialize the MCP connection and call tools/list. If using the JSON-RPC gateway, call call.dial first, then tools/list.
2. Use the direct tool names returned by tools/list.
3. If it is about to work inside an existing project, call get_onto_project_status with the project_id first.

get_onto_project_status is the BuildOS equivalent of git status for a project. It returns the compact snapshot an agent needs before deeper reads or writes: START HERE orientation context, project description, task/document/plan/goal/collaborator counts, active collaborators, recent changes, overdue and due-soon tasks, and upcoming events.

Client profiles

Same BuildOS auth core. Different save location.

Client profile	Best storage path	Status
OpenClaw	OpenClaw env, SecretRef, or plugin config	BuildOS side ready; OpenClaw connector in progress
Claude Code	claude mcp add with a bearer header or OAuth	Remote HTTP MCP ready at /mcp/buildos
Claude Desktop / local MCP hosts	Local stdio bridge env vars, or direct remote MCP if supported	Bridge exists in repo; package is not published to npm
ChatGPT Actions	GPT Action API key secret	Ready for private GPTs; use OAuth before sharing broadly
ChatGPT MCP / Apps	Remote MCP OAuth connector	OAuth remote MCP ready at /mcp/buildos
Codex CLI / IDE	~/.codex/config.toml with bearer_token_env_var	Remote MCP config ready; local bridge available
Custom HTTP / scripts	Your env file or secret manager	Ready

BuildOS speaks the Model Context Protocol at /mcp/buildos. Local clients can authenticate with the agent key in an Authorization: Bearer header or an env-backed MCP config; browser/cloud clients (Claude.ai, ChatGPT) authenticate with OAuth — no pasted token. The older JSON-RPC gateway at POST /api/agent-call/buildos (the call.dial → tools/list → tools/call → call.hangup flow) still works for any HTTP-capable tool and is the fallback when a client can’t speak MCP.

The MCP endpoint supports three profiles:

Profile	URL	Tool surface
general	/mcp/buildos	Scoped BuildOS read/write tools; discovery tools are hidden.
chatgpt_data_app	/mcp/buildos?profile=chatgpt_data_app	Read-only search and fetch only, even if the underlying grant allows writes.
local_admin	/mcp/buildos?profile=local_admin	Full scoped surface including skill_load, tool_search, and tool_schema. Use only for local/admin clients you control.

Generate an agent key

1. Go to /profile and open the Agent Keys tab.
2. Click Generate.
3. Choose the Client Profile for the place this key will be installed.
4. Pick a scope:
   • read_only — reads only, no writes.
   • read_write — reads plus the writes you whitelist.
5. Choose which projects the key can see — all of them or an explicit list.
6. If you picked read_write, whitelist the specific write ops.
7. Copy the profile-specific setup block. The one-time secret shows only once; BuildOS stores a prefix for identification and never the full key.
8. Save it in the profile’s config, secret store, Action auth field, or connector backend.

/integrations has the same flow plus the public landing page.

Setting it up in Claude Code

Choose the Claude Code client profile when generating the key, then add BuildOS as an MCP server. The Agent Keys tab shows this exact command (with your key filled in):

claude mcp add --transport http buildos https://build-os.com/mcp/buildos --header "Authorization: Bearer boca_your_one_time_secret"

Restart Claude Code and BuildOS tools appear. Then prompt:

“Connect to BuildOS and list my projects.”

When you pick a project, ask it to call get_onto_project_status before deeper reads or writes — it’s a compact, git-status-style snapshot of the project.

Prefer not to paste a key? Run the same command without --header:

claude mcp add --transport http buildos https://build-os.com/mcp/buildos

Then run /mcp inside Claude Code and follow the browser login flow. Claude Code discovers BuildOS’s OAuth metadata, and you approve scope and projects — no token stored locally.

The JSON-RPC gateway at POST /api/agent-call/buildos remains available as a fallback if you’d rather drive the call.dial flow directly with the env block:

BUILDOS_BASE_URL=https://build-os.com
BUILDOS_AGENT_TOKEN=boca_your_one_time_secret
BUILDOS_CALLEE_HANDLE=buildos:user:YOUR_USER_ID
BUILDOS_CALLER_KEY=claude-code:local:your-handle

Setting it up in Cursor

Use the direct remote MCP URL if your Cursor build supports remote HTTP MCP:

URL: https://build-os.com/mcp/buildos
Header: Authorization: Bearer boca_your_one_time_secret

If your Cursor setup only launches local stdio MCP servers, use the local bridge in packages/buildos-mcp-server:

pnpm --filter @buildos/mcp-server build

Then point Cursor’s MCP config at the built entrypoint:

{
	"mcpServers": {
		"buildos": {
			"command": "node",
			"args": [
				"/absolute/path/to/buildos-platform/packages/buildos-mcp-server/dist/index.js"
			],
			"env": {
				"BUILDOS_BASE_URL": "https://build-os.com",
				"BUILDOS_AGENT_TOKEN": "boca_your_agent_key"
			}
		}
	}
}

Then prompt:

“Connect to BuildOS, list my projects.”

For project work, ask it to call get_onto_project_status first so it has the current project snapshot.

Setting it up in Claude Desktop and Claude browser

There are two different paths:

• Claude Desktop / local MCP hosts can use direct remote HTTP MCP if supported, or the local stdio bridge in packages/buildos-mcp-server when the client expects a local process.
• Claude browser or cloud-brokered remote connectors authenticate with OAuth, not a pasted token. Browser chat is not a secret store, and Claude’s cloud cannot read your local env.

For browser/cloud clients, add https://build-os.com/mcp/buildos as a custom/remote MCP connector. BuildOS publishes OAuth metadata, so the client takes you through a consent screen where you pick scope and projects, then issues its own token behind the scenes. Nothing to copy or paste.

Setting it up in Codex

Choose Codex CLI / IDE when generating the key. Add BuildOS to ~/.codex/config.toml and keep the secret in your environment:

[mcp_servers.buildos]
url = "https://build-os.com/mcp/buildos"
bearer_token_env_var = "BUILDOS_AGENT_TOKEN"

export BUILDOS_AGENT_TOKEN=boca_your_one_time_secret

If a Codex surface only supports local stdio MCP servers, use the same local bridge shown in the Cursor section. For direct remote MCP, append ?profile=chatgpt_data_app to the URL only when you intentionally want a read-only search/fetch surface; for the local bridge, set BUILDOS_MCP_PROFILE=chatgpt_data_app.

Setting it up in ChatGPT (Custom GPT)

Choose ChatGPT Actions for a private Custom GPT:

1. In your Custom GPT, add a new Action.
2. Use API key auth with Bearer placement, and paste the one-time BuildOS token into the Action authentication secret.
3. Import the OpenAPI artifact from the BuildOS bootstrap document.
4. Point it at POST https://build-os.com/api/agent-call/buildos with a JSON-RPC body.

The Custom GPT can then run call.dial → tools/list → tools/call → call.hangup like any other client.

For shared GPTs or workspace-wide installs, use OAuth instead of a single bearer token.

Setting it up in ChatGPT Developer Mode

Choose ChatGPT Developer Mode only when you are building a remote MCP connector. Developer Mode is the right path for MCP tools in ChatGPT, but it should be backed by remote MCP and OAuth, not a pasted BuildOS bearer token.

Use https://build-os.com/mcp/buildos?profile=chatgpt_data_app when ChatGPT should only search and fetch BuildOS context. Use https://build-os.com/mcp/buildos only for trusted full-tool connectors where the OAuth grant and BuildOS scope allow the requested writes.

Setting it up in OpenClaw

Choose OpenClaw when generating the key. Store the values in OpenClaw env, SecretRef, or plugin config. The OpenClaw-specific connector is still mid-build. Once it ships, it should read those values and call the BuildOS gateway.

What you can scope

Control	What it does
Mode	read_only blocks every write op. read_write allows the ones you whitelist.
Project scope	All projects or an explicit allowlist. Keys can’t reach projects outside the list.
Write op whitelist	Per-op toggle for every mutation the gateway exposes.
Audit trail	Every call is logged with the key prefix, the op, and the entity touched.

Permission bundles

The Agent Keys UI leads with preset bundles. Pick one and you’re done — the per-op matrix sits behind an Advanced permissions disclosure if you need finer control.

Bundle	What it grants
Read only	Every read op. No writes.
Author docs + tasks (recommended default)	Reads plus onto.document.create/update and onto.task.create/update.
Full read/write	Reads plus every write op the gateway currently exposes.
Custom	Any per-op combination you pick in Advanced.

Existing OpenClaw keys that still carry the old narrow default (task writes only) auto-upgrade to Author docs + tasks on the next call — no action needed.

Project creation is its own write op: onto.project.create requires read_write and the op whitelisted. It is not tied to all-project access — a key scoped to selected projects can still create new ones, and each project it creates is automatically added to that key’s scope so it can immediately read and write the project it just made. To prevent a key from creating projects, leave onto.project.create out of its write whitelist.

What’s exposed

Reads (available on every key)

• Projects: onto.project.list, onto.project.search, onto.project.get, onto.project.status.get, onto.project.graph.get
• Tasks: onto.task.list, onto.task.search, onto.task.get, onto.task.docs.list
• Documents: onto.document.list, onto.document.search, onto.document.get, onto.document.tree.get, onto.document.path.get
• Goals, plans, milestones, risks: list/search/get for each entity
• Assets: onto.asset.search, onto.asset.get
• Links: onto.entity.relationships.get, onto.entity.links.get
• Search: onto.search
• Calendar: cal.event.list, cal.event.get, cal.project.get

Writes (require read_write)

• onto.task.create, onto.task.update
• onto.task.docs.create_or_attach
• onto.document.create, onto.document.update
• onto.document.tree.move
• onto.project.create, onto.project.update
• onto.goal.create, onto.goal.update
• onto.plan.create, onto.plan.update
• onto.milestone.create, onto.milestone.update
• onto.risk.create, onto.risk.update
• onto.edge.link, onto.edge.unlink
• cal.event.create, cal.event.update, cal.event.delete
• cal.project.set

Discovery

• skill_load, tool_search, tool_schema are available through the JSON-RPC gateway and through MCP only when using ?profile=local_admin.

JSON-RPC gateway session methods

• call.dial, tools/list, tools/call, call.hangup

MCP resources

• resources/list exposes in-scope projects as START HERE orientation resources.
• resources/read accepts buildos://project/<id> and buildos://document/<id>.

Getting Project Status

The project status op is onto.project.status.get, exposed by tools/list as get_onto_project_status. It is read-only and available on normal read grants.

Use it when an agent first attaches to a known project, before it starts searching individual tasks or documents. It returns:

• overview: short description, task/document/plan/goal/collaborator counts, count summary, and next step when available
• collaborators: active project members with actor ID, display name, email when available, role/access, role profile, and whether the member is the connected user
• recent_changes: most recent project log entries with entity type, action, title, timestamp, and source
• upcoming: overdue tasks, due-soon tasks, upcoming project events, and the time windows used

If the agent does not know the project ID yet, it can list/search projects first, or pass a query if the status tool is available and the project name is clear.

For MCP clients, call get_onto_project_status through the client’s normal tool-call UI with the same arguments object. The call_id wrapper below is only for the JSON-RPC gateway.

{
	"method": "tools/call",
	"params": {
		"call_id": "<your call id>",
		"name": "get_onto_project_status",
		"arguments": {
			"project_id": "<project uuid>"
		}
	}
}

Saving a markdown document from an external agent

The headline v1 write op is onto.document.create, exposed by tools/list as create_onto_document. Any connected tool can save a markdown artifact into a specific project in a single call.

For MCP clients, call create_onto_document directly with the same arguments object. The method and call_id wrapper below is only for the JSON-RPC gateway.

{
	"method": "tools/call",
	"params": {
		"call_id": "<your call id>",
		"name": "create_onto_document",
		"arguments": {
			"project_id": "<project uuid>",
			"title": "Research: creator distribution loops",
			"content": "# Research\n\nFull markdown body here...",
			"description": "Initial pass on distribution tactics",
			"state_key": "draft",
			"idempotency_key": "claude-code:<project>:research-creator-distribution-loops:2026-05-11"
		}
	}
}

Notes:

• Content is stored as-is. No H1/H2 tree parsing; the markdown you send is the markdown we save.
• Content cap is 200 KB per document. Larger bodies return VALIDATION_ERROR.
• Use content for document bodies. External direct tools reject legacy compatibility parameters such as body_markdown and parent_id with VALIDATION_ERROR so agents learn the canonical schema.
• onto.document.update defaults to replace. It also accepts update_strategy: "append" and update_strategy: "merge_llm"; on the external gateway, merge_llm gracefully falls back to append when no merge worker is available.
• parent_document_id is optional; omit it to land at the project root.
• Use parent_document_id for tree placement; parent_id is not accepted on the external direct tool.
• position is optional on create for sibling ordering within the project document tree.
• Documents created through the gateway are tagged with props.origin = "external_agent" for auditability.

Creating a project from an external agent

The project creation op is onto.project.create, exposed by tools/list as create_onto_project. It uses the same ProjectSpec contract as internal BuildOS project creation: include project, entities, and relationships; use empty arrays when the new project should start minimal.

For MCP clients, call create_onto_project directly with the same arguments object. The method and call_id wrapper below is only for the JSON-RPC gateway.

{
	"method": "tools/call",
	"params": {
		"call_id": "<your call id>",
		"name": "create_onto_project",
		"arguments": {
			"idempotency_key": "claude-code:project:creator-launch-plan:2026-05-21",
			"project": {
				"name": "Creator Launch Plan",
				"type_key": "project.business.product_launch",
				"description": "Plan and assets for launching the creator product."
			},
			"entities": [],
			"relationships": []
		}
	}
}

Notes:

• project.type_key must use the project.{realm}.{domain} format, for example project.business.product_launch.
• entities can include initial task, document, goal, plan, milestone, risk, requirement, metric, and source records using temp_id references.
• relationships connects temp_id entities to each other. The project itself is implicit and should not be a relationship endpoint.
• Optional context_document creates a document.context.project document linked to the project.
• Project-scoped keys can create projects when onto.project.create is whitelisted. The created project is added to that key’s project scope automatically.

One-click bootstrap

When you generate a key in the UI, BuildOS also produces a bootstrap URL:

GET /api/agent-call/bootstrap/<setupToken>

That endpoint returns an agent_profile_bootstrap_v1 document with:

• the BuildOS env block
• client-specific storage targets
• setup steps
• artifacts such as a ChatGPT Action OpenAPI schema or MCP config target notes
• guidance to call get_onto_project_status first for existing project work
• OAuth guidance for browser/cloud clients

It is short-lived and returns Cache-Control: no-store.

Custom agents

If you’re building your own client, point it at:

POST https://build-os.com/api/agent-call/buildos
Authorization: Bearer <your agent key>
Content-Type: application/json

Payload is JSON-RPC. Start with call.dial, list your tools with tools/list, call them via tools/call, and close with call.hangup. Types live in packages/shared-types/src/agent-call.types.ts.

Roadmap

• Project, document, task, goal, plan, milestone, risk, link, and calendar writes — shipped. External agents can create and update the same core ontology primitives used by internal BuildOS chat, subject to scope, write audit, and idempotency.
• Content idea wrappers — still planned. They should compose the shipped primitives rather than inventing a separate top-level entity.

Design doc: apps/web/docs/features/agent-call/MULTI_SURFACE_CONTENT_IDEA_WORKFLOW.md.

Next

• Reference & Help
• Integrations — per-agent setup walk-throughs.