Setting up MCP

MCP (Model Context Protocol) lets agent hosts — Claude Code, VS Code, Codex, Windsurf, and any other MCP-capable client — read a workspace's knowledge through one permission-aware connection. An agent only ever sees what the identity that connected it is allowed to see.

Your endpoint

Every workspace gets its own MCP server URL — not the REST API host:

https://mcp.aize.dev/{workspace_id}

Find your exact URL (with the real workspace id filled in) under Channels → MCP in the dashboard. A common mistake porting an old integration: the MCP host is mcp.aize.dev, never apibr.aize.dev/mcp — the REST API and the MCP server are different hosts entirely.

Authentication

Production MCP auth is OAuth 2.1 with token exchange, not a REST API key. The client id is braize-mcp-cli, scope mcp:read, and the resource is your MCP endpoint's origin (https://mcp.aize.dev). Each config below wires that up for its host. (A bzk_ bearer key is accepted as a dev-only convenience gated behind a server-side flag — it is not the integration path to build against.)

Client configs

Replace https://mcp.aize.dev/{workspace_id} with your real endpoint from the dashboard.

Claude Code

claude mcp add --transport http braize https://mcp.aize.dev/{workspace_id} \
  --oauth-client-id braize-mcp-cli \
  --scope mcp:read \
  --resource https://mcp.aize.dev

Codex (config.toml)

[mcp_servers.braize]
url = "https://mcp.aize.dev/{workspace_id}"
client_id = "braize-mcp-cli"
scope = "mcp:read"
resource = "https://mcp.aize.dev"

Windsurf (mcp_config.json)

{
  "mcpServers": {
    "braize": {
      "serverUrl": "https://mcp.aize.dev/{workspace_id}",
      "oauth": { "clientId": "braize-mcp-cli", "scope": "mcp:read", "resource": "https://mcp.aize.dev" }
    }
  }
}

VS Code (.mcp.json)

{
  "servers": {
    "braize": {
      "type": "http",
      "url": "https://mcp.aize.dev/{workspace_id}",
      "oauth": { "clientId": "braize-mcp-cli", "scope": "mcp:read", "resource": "https://mcp.aize.dev" }
    }
  }
}

What agents can do

Four tools, published and stable — see the full MCP tool reference for exact input/output schemas:

• search_knowledge — permission-aware hybrid search returning ranked, cited passages (the same retrieval /v1/retrieve uses). The agent synthesizes its own answer; Braize doesn't generate prose for this tool.
• get_document — fetch one document's full detail (version history, parse status, freshness) by id.
• list_sources — list the connectors feeding the workspace, with sync health and indexed-document counts.
• get_freshness_report — check how current the answers are before relying on them.

Tool and parameter names are immortal — a new capability always arrives as a new tool, never a rename or a repurposed parameter.

MCP status

MCP is in beta: the contract, the OAuth flow, and the four tools above are real and live. Ongoing work is client-compatibility verification across hosts, not the protocol surface itself.