Connect a Coding Agent (MCP)

The SyntheticBrew Engine exposes its own Model Context Protocol (MCP) server over Streamable HTTP at POST /api/v1/mcp/rpc. Connect your coding agent (Claude Code, Cursor, or any MCP client) to it and you can provision a fully working, embeddable chat agent by talking to your assistant in plain language — no dashboard clicks, no YAML.

This is the fastest path from a running engine to a chat widget on your site.

This is your engine, not the docs server

This page connects your assistant to your own engine’s management MCP server (/api/v1/mcp/rpc) so it can create agents, models, and MCP servers. That is different from the public documentation MCP server (mcp.syntheticbrew.ai/sse) covered in the Quick Start, which only searches these docs.

Step 1: Connect your agent

On SyntheticBrew Cloud, connect by URL and sign in through your browser — there is no token to copy. Your agent runs the OAuth handshake for you.

Claude Code

Run these in your project directory:

claude mcp add --transport http syntheticbrew https://app.syntheticbrew.ai/api/v1/mcp/rpc
claude mcp login syntheticbrew

A browser opens; sign in and approve the consent screen. No token to copy.

Cursor

Add the server to ~/.cursor/mcp.json — URL only, no headers:

{
  "mcpServers": {
    "syntheticbrew": {
      "type": "http",
      "url": "https://app.syntheticbrew.ai/api/v1/mcp/rpc"
    }
  }
}

Cursor opens a browser to sign in automatically.

VS Code

code --add-mcp '{"name":"syntheticbrew","type":"http","url":"https://app.syntheticbrew.ai/api/v1/mcp/rpc"}'

VS Code opens a browser to sign in.

OpenAI Codex

codex mcp add syntheticbrew --url https://app.syntheticbrew.ai/api/v1/mcp/rpc
codex mcp login syntheticbrew

A browser opens; sign in and approve the consent screen.

How the sign-in works

Your agent discovers OAuth automatically — it reads the server’s RFC 9728 protected-resource metadata, registers itself as a client, and opens your browser to syntheticbrew.ai for consent. The consent screen lets you grant provision (create & configure agents, models, and MCP servers) and, optionally, manage (destructive operations such as delete). After you approve, the agent stores the access token and refreshes it itself — you never see or copy a token.

Transport

The engine’s management MCP server speaks Streamable HTTP. In Cloud deployments the stdio transport is blocked by policy, so always use http (or sse) here.

Self-hosted engine

A self-hosted CE engine has no OAuth server, so browser sign-in is not available — the auth is a scoped bb_ token you mint yourself.

1. Open Admin Dashboard → API Keys.
2. Click Connect a coding agent.
3. Leave the default scope on provision — this lets the agent create and read agents, models, and MCP servers, which covers the whole provisioning flow. Tick Allow destructive operations (manage) only if the agent must delete or overwrite existing configuration.
4. The token is shown once — copy it immediately. It is prefixed with bb_.

Then add the server with the token in an Authorization header:

claude mcp add --transport http syntheticbrew <ENGINE_URL>/api/v1/mcp/rpc \
  --header "Authorization: Bearer <token>"

Replace <ENGINE_URL> with your engine’s base URL (e.g. http://localhost:8443 or https://engine.example.com) and <token> with the bb_ token.

The same Authorization: Bearer <token> header carries the auth for the other agents — Cursor takes it under headers in mcpServers, VS Code under "headers" in --add-mcp, and Codex via an env var:

{
  "mcpServers": {
    "syntheticbrew": {
      "type": "http",
      "url": "<ENGINE_URL>/api/v1/mcp/rpc",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

code --add-mcp '{"name":"syntheticbrew","type":"http","url":"<ENGINE_URL>/api/v1/mcp/rpc","headers":{"Authorization":"Bearer <token>"}}'

export SYNTHETICBREW_TOKEN=<token>
codex mcp add syntheticbrew --url <ENGINE_URL>/api/v1/mcp/rpc --bearer-token-env-var SYNTHETICBREW_TOKEN

Copy the token immediately

Like every API key, the token is hashed before storage and cannot be recovered. If you lose it, revoke it and mint a new one.

Step 2: What your agent can do

Once connected, your assistant sees 34 tools. The two you will use most:

Tool	What it does
provision_agent	One call that creates a chat-enabled schema, the agent, and binds the agent as the schema’s entry point — the end result is something users can chat with immediately.
get_embed_snippet	Returns a ready-to-paste <script> embed for a chat-enabled schema, including a freshly minted chat-scoped bb_ key (shown once).

The remaining tools are the admin_* management family — create, list, update, and delete models, MCP servers, agents, schemas, capabilities, and agent relations, plus attach/detach MCP servers and inspect sessions. Your assistant calls them as needed while you describe what you want.

provision_agent arguments

Argument	Required	Description
name	Yes	Unique agent name (lowercase letters, digits, hyphens; must start with a letter).
system_prompt	Yes	The system prompt defining role, scope, refusals, and tone. This is the single biggest lever on agent quality.
schema_name	No	Chat schema name. Defaults to the agent name.
model_name	No	Model to bind. If omitted, the agent uses the deployment’s default model when one is available.
tools	No	Array of built-in tool names to grant the agent.

get_embed_snippet arguments

Argument	Required	Description
schema_name	Yes	Name of the chat-enabled schema to embed.
endpoint	No	Public engine base URL (e.g. https://engine.example.com). If omitted, the snippet uses a placeholder you must replace with your engine’s public URL.

Step 3: A typical provisioning flow

You do not call these by hand — you tell your assistant what you want and it chains the tools. A common sequence:

1. Connect (Step 1).
2. (Optional) admin_create_model — register the LLM the agent should use. Skip this to fall back to the deployment default (see below).
3. provision_agent — create the chat-ready schema + agent in one call.
4. (Optional) admin_create_mcp_server + admin_attach_mcp_server_to_agent — give the agent external tools.
5. get_embed_snippet — get the <script> tag.
6. Paste the snippet on your site.

For example, a prompt like “Provision a support agent called checkout-help that answers questions about our checkout product, then give me the embed snippet for https://shop.example.com” drives provision_agent followed by get_embed_snippet.

No model? Use the deployment default

If you skip the model step and provision an agent without a model, the agent can still chat immediately when the deployment has a platform/operator default model installed. A model configured on the tenant or agent always takes precedence. In self-hosted CE there is no platform default — configure a model first. See Platform default model.

Step 4: Embed the chat widget

get_embed_snippet returns a single <script> tag:

<script
  src="<ENGINE_URL>/widget.js"
  data-schema="<schema>"
  data-api-key="bb_...">
</script>

• src points at the engine’s widget.js.
• data-schema is the chat-enabled schema name.
• data-api-key is a chat-scoped key, minted once by get_embed_snippet. It can only send chat messages to that schema.

Paste it into any HTML page — a landing page, a docs site, a dashboard — and a chat widget backed by your agent appears. No build step, no framework required.

The embed key is shown once

The data-api-key in the snippet is minted once and is not recoverable. Store the snippet somewhere safe. If it leaks, revoke that key in Admin Dashboard → API Keys and generate a fresh snippet.

---

What’s next

• Admin Dashboard: API Keys — mint and revoke tokens
• Admin Dashboard: MCP Servers — add external tools to your agent
• Model Selection — choose (or default) the agent’s model
• REST API Chat — drive the same chat over SSE from your own client