Connect a Coding Agent

Connect a coding agent to SyntheticBrew’s management MCP server when you want to create and configure platform resources from your editor or terminal. The server uses Streamable HTTP at /api/v1/mcp/rpc and advertises discovery metadata, server identity, and setup instructions during MCP initialization.

SyntheticBrew Cloud is available at:

https://app.syntheticbrew.ai/api/v1/mcp/rpc

For Enterprise, replace https://app.syntheticbrew.ai with the public URL configured by your operator.

Before you begin

Sign in to SyntheticBrew in a browser.
Confirm the client supports remote HTTP MCP and OAuth.
Ask for provision authority for normal setup work. Grant manage only if the coding agent must delete resources or replace existing Knowledge Graph bundles.
For Enterprise, the operator must configure the public URL, OAuth issuer, and shared signing keys before browser authorization works.

Connect with OAuth

OAuth is the recommended setup because the client stores and refreshes its own scoped credentials.

Claude Code

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

Cursor

Add SyntheticBrew to Cursor, or add it manually:

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

VS Code

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

OpenAI Codex

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

Your client discovers the OAuth endpoints, opens the SyntheticBrew consent screen, and waits on its loopback callback. Review the requested scopes, approve the connection, and return to the client.

When the browser and coding agent are on different machines

The callback points to a loopback address on the machine running the coding agent. A browser on your laptop cannot directly reach that callback when the agent runs over SSH, in a container, or on another workstation.

After approval, SyntheticBrew opens the callback in a second tab and keeps the consent tab on a handover screen. If the callback tab cannot connect:

Return to the consent tab.
Choose Copy URL.
Paste the complete callback URL into the coding agent’s terminal prompt.
Keep the consent tab open until it confirms that the code was redeemed.

Authorization codes are single-use and expire after five minutes. The handover screen shows the remaining lifetime and checks exchange status so it can complete automatically when the client redeems the code. A temporary connection failure does not discard a still-valid handover; an invalid or unauthorized status check stops with an error.

For repeatable container setups, pin the client’s callback port and forward that port to the host running the coding agent. URL handover remains the recovery path when forwarding is not available.

If the consent screen asks you to sign in again, complete sign-in and resume the authorization request. SyntheticBrew detects expired browser sessions instead of leaving the approval flow stuck. If the code expires, return to the client and start a new login; do not reuse the old callback URL.

Use a scoped key only when OAuth is unsuitable

A manual key is appropriate for CI, a headless environment, or a client without OAuth support.

Open API Keys in Admin.
Expand Connecting a coding agent manually (per-client instructions).
Leave Allow destructive operations (manage) off for normal setup; enable it only when the agent must delete or replace resources.
Choose Generate connection token and copy the bb_ key when it is shown. It cannot be recovered later.
Select your client tab and copy the generated configuration, which sends the key as an Authorization: Bearer header.

claude mcp add --transport http syntheticbrew "$SYNTHETICBREW_URL/api/v1/mcp/rpc" \
  --header "Authorization: Bearer $SYNTHETICBREW_TOKEN"

For clients that store JSON configuration:

{
  "mcpServers": {
    "syntheticbrew": {
      "type": "http",
      "url": "https://your-enterprise.example/api/v1/mcp/rpc",
      "headers": {
        "Authorization": "Bearer bb_replace_once"
      }
    }
  }
}

Prefer an environment variable or secret store over committing a key to the configuration file. Revoke the key from API Keys when the client is retired.

Provision and verify an agent

Once connected, ask the coding agent to list the available tools before making changes. The catalog includes platform management tools for schemas, agents, models, MCP servers, Knowledge, Knowledge Graphs, capabilities, and agent relationships.

A typical workflow is:

Inspect schemas and models already available.
Create a model only when no suitable deployment default exists.
Call provision_agent with a name and system prompt to create a chat schema, entry agent, and binding.
Add Knowledge, a Knowledge Graph, or external MCP tools as required.
Test a new session.
Call get_embed_snippet with the schema name when a web embed is needed.

get_embed_snippet creates a chat-scoped key and returns the complete credential-bearing snippet once. The appearance snippet shown on the Widgets page deliberately contains no credential and is not a deployable chat embed by itself.

Expected result

The MCP client reports SyntheticBrew as connected, shows the management catalog, and can read the resources allowed by its scopes. A provisioned agent appears in Agents, and its chat-enabled schema appears in Schemas.

Troubleshooting

The browser shows a localhost error: use the callback URL on the consent handover screen and paste it into the remote client’s prompt before the five-minute expiry.

The consent page cannot approve: sign in again. An expired Admin session should recover; restart the client login if the authorization request itself expired.

The client cannot reach SyntheticBrew: confirm the configured URL ends in /api/v1/mcp/rpc, then test that the same origin is reachable from the machine running the coding agent. The MCP Servers page monitors external tool servers and does not represent this management connection. For Cloud, retry and contact support if the service remains unreachable. For Enterprise, ask the deployment administrator to check the public URL, proxy, health endpoint, and service logs.

The agent cannot delete or replace a graph: reconnect with manage authority, or use an incremental non-destructive operation with provision authority.

The generated widget cannot chat: use get_embed_snippet; the Widgets appearance snippet does not mint or expose keys.