Spec: Ambient Platform MCP Server

Date: 2026-03-22 Status: Design Workflow: ../../workflows/integrations/mcp-server.workflow.md — implementation waves, gap table, build commands, run log

Overview

The Ambient Platform MCP Server exposes the platform's resource API as a set of structured tools conforming to the Model Context Protocol (MCP) 2024-11-05. It has two deployment modes:

Sidecar — runs alongside the Claude Code CLI in every runner Job pod. Claude Code connects via stdio. The sidecar's auth token is injected from the pod environment.
Public endpoint — exposed through ambient-api-server at POST /api/ambient/v1/mcp. Clients authenticate with the same bearer token used for all other API calls. The frontend session panel connects here.

The MCP server has no direct Kubernetes access. All operations proxy through ambient-api-server, inheriting the full RBAC model.

Component

Location: components/ambient-mcp/

Language: Go 1.24+

Library: mark3labs/mcp-go v0.45.0

Constraint: No direct Kubernetes API access. Reads and writes go through the platform REST API only.

Image: localhost/vteam_ambient_mcp:latest

Directory Structure

components/ambient-mcp/
├── main.go              # Entrypoint; transport selected by MCP_TRANSPORT env var
├── server.go            # MCP server init, capability declaration, tool registration
├── Dockerfile           # ubi9/go-toolset builder → ubi9/ubi-minimal runtime, UID 1001
├── go.mod               # module: github.com/ambient-code/platform/components/ambient-mcp
├── client/
│   └── client.go        # Thin HTTP client wrapping ambient-api-server
├── mention/
│   └── resolve.go       # @mention extraction and agent resolution
└── tools/
    ├── helpers.go        # jsonResult / errResult utilities
    ├── sessions.go       # Session tool handlers + annotation merge
    ├── agents.go         # Agent tool handlers + annotation merge
    ├── projects.go       # Project tool handlers + annotation merge
    └── watch.go          # watch_session_messages, unwatch_session_messages

Configuration

Environment Variable	Required	Default	Description
`AMBIENT_API_URL`	Yes	—	Base URL of the ambient-api-server
`AMBIENT_TOKEN`	Yes	—	Bearer token. In sidecar mode, injected from the pod's service environment. In public-endpoint mode, forwarded from the HTTP request.
`MCP_TRANSPORT`	No	`stdio`	`stdio` for sidecar mode, `sse` for public endpoint
`MCP_BIND_ADDR`	No	`:8090`	Bind address for SSE mode

MCP Protocol

Initialize

The server declares the following capabilities in its initialize response:

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {}
  },
  "serverInfo": {
    "name": "ambient-platform",
    "version": "1.0.0"
  }
}

Resources and prompts capabilities are not declared. All platform operations are exposed as tools.

Transports

Mode	Transport	Binding
Sidecar (runner pod)	stdio	stdin/stdout of the sidecar process
Public endpoint	SSE over HTTP	`MCP_BIND_ADDR` (proxied through `ambient-api-server`)

In SSE mode, the server responds to:

GET /sse — SSE event stream (client → server messages via query param or POST)
POST /message — client sends JSON-RPC messages; server replies via the SSE stream

Error Format

All tool errors follow MCP's structured error response. The content array contains a single text item with a JSON-encoded error body matching the platform's Error schema:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"code\": \"SESSION_NOT_FOUND\", \"reason\": \"no session with id abc123\", \"operation_id\": \"get_session\"}"
    }
  ]
}

Tool Definitions

`list_sessions`

Lists sessions visible to the caller, with optional filters.

RBAC required: sessions:list

Backed by: GET /api/ambient/v1/sessions

Input schema:

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Filter to sessions belonging to this project ID. If omitted, returns all sessions visible to the caller's token."
    },
    "phase": {
      "type": "string",
      "enum": ["Pending", "Running", "Completed", "Failed"],
      "description": "Filter by session phase."
    },
    "page": {
      "type": "integer",
      "description": "Page number (1-indexed). Default: 1."
    },
    "size": {
      "type": "integer",
      "description": "Page size. Default: 20. Max: 100."
    }
  }
}

Return value: JSON-encoded SessionList. Content type text, format:

{
  "kind": "SessionList",
  "page": 1,
  "size": 20,
  "total": 3,
  "items": [
    {
      "id": "3BEaN6kqawvTNUIXoSMcgOQvUDj",
      "name": "my-session",
      "project_id": "demo-6640",
      "phase": "Running",
      "created_at": "2026-03-21T10:00:00Z",
      "llm_model": "claude-sonnet-4-6"
    }
  ]
}

Errors:

Code	Condition
`UNAUTHORIZED`	Token invalid or expired
`FORBIDDEN`	Token lacks `sessions:list`
`INTERNAL`	Backend returned 5xx

`get_session`

Returns full detail for a single session.

RBAC required: sessions:get

Backed by: GET /api/ambient/v1/sessions/{id}

Input schema:

{
  "type": "object",
  "required": ["session_id"],
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Session ID (UUID)."
    }
  }
}

Return value: JSON-encoded Session.

Errors:

Code	Condition
`SESSION_NOT_FOUND`	No session with that ID
`UNAUTHORIZED`	Token invalid or expired
`FORBIDDEN`	Token lacks `sessions:get`

`create_session`

Creates and starts a new agentic session. The session enters Pending phase immediately and transitions to Running when the operator schedules the runner pod.

RBAC required: sessions:create

Backed by: POST /api/ambient/v1/sessions, then POST /api/ambient/v1/sessions/{id}/start

Input schema:

{
  "type": "object",
  "required": ["project_id", "prompt"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project (Kubernetes namespace) in which to create the session. Must match the caller's token scope."
    },
    "prompt": {
      "type": "string",
      "description": "Task prompt for the session. Passed as Session.prompt to the runner."
    },
    "agent_id": {
      "type": "string",
      "description": "ID of the ProjectAgent to execute this session. If omitted, the project's default agent is used."
    },
    "model": {
      "type": "string",
      "description": "LLM model override (e.g. 'claude-sonnet-4-6'). If omitted, the agent's configured model is used."
    },
    "parent_session_id": {
      "type": "string",
      "description": "ID of the calling session. Used for agent-to-agent delegation. Sets Session.parent_session_id. The child session appears in the parent's lineage."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for the session. If omitted, a name is generated from the prompt (first 40 chars, slugified)."
    }
  }
}

Return value: JSON-encoded Session in Pending phase.

Behavior:

Creates the Session CR via POST /api/ambient/v1/sessions
Immediately calls POST /api/ambient/v1/sessions/{id}/start
Returns the created Session object
Does not wait for the session to reach Running — the caller must poll or watch_session_messages to observe progress

Errors:

Code	Condition
`INVALID_REQUEST`	`project_id` or `prompt` missing
`AGENT_NOT_FOUND`	`agent_id` specified but does not exist
`FORBIDDEN`	Token lacks `sessions:create` or is not scoped to `project_id`
`INTERNAL`	Backend returned 5xx

`push_message`

Appends a user message to a session's message log. Supports @mention syntax for agent-to-agent delegation (see @mention Pattern).

RBAC required: sessions:patch

Backed by: POST /api/ambient/v1/sessions/{id}/messages

Input schema:

{
  "type": "object",
  "required": ["session_id", "text"],
  "properties": {
    "session_id": {
      "type": "string",
      "description": "ID of the target session."
    },
    "text": {
      "type": "string",
      "description": "Message text. May contain @agent_id or @agent_name mentions to trigger agent delegation."
    }
  }
}

Return value: JSON object with the following fields:

{
  "message": { /* SessionMessage */ },
  "delegated_session": null
}

If the message contained a resolvable @mention, delegated_session is the newly created child Session; otherwise it is null.

Behavior:

Pushes the message to the session with event_type: "user"
If text contains one or more @mention tokens, each is resolved and a child session is created (see @mention Pattern)
The original message is pushed as-is (including the @mention text) before delegation

Errors:

Code	Condition
`SESSION_NOT_FOUND`	No session with that ID
`SESSION_NOT_RUNNING`	Session is in `Completed` or `Failed` phase. Messages cannot be pushed to terminal sessions.
`MENTION_NOT_RESOLVED`	`@mention` token could not be matched to any agent
`FORBIDDEN`	Token lacks `sessions:patch`

`patch_session_labels`

Merges key-value label pairs into a session's labels field. Existing labels not present in the patch are preserved.

RBAC required: sessions:patch

Backed by: PATCH /api/ambient/v1/sessions/{id}

Input schema:

{
  "type": "object",
  "required": ["session_id", "labels"],
  "properties": {
    "session_id": {
      "type": "string",
      "description": "ID of the session to update."
    },
    "labels": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Key-value label pairs to merge. Keys and values must be non-empty strings. Keys may not contain '=' or whitespace.",
      "example": {"env": "prod", "team": "platform"}
    }
  }
}

Return value: JSON-encoded updated Session.

Behavior:

Reads existing Session.labels (JSON-decoded from its stored string form)
Merges the provided labels (provided keys overwrite existing values)
Writes back via PATCH /api/ambient/v1/sessions/{id} with the merged label map serialized to JSON string

Errors:

Code	Condition
`SESSION_NOT_FOUND`	No session with that ID
`INVALID_LABEL_KEY`	A key contains `=` or whitespace
`INVALID_LABEL_VALUE`	A value is empty
`FORBIDDEN`	Token lacks `sessions:patch`

`watch_session_messages`

Subscribes to a session's message stream. Returns a subscription_id immediately. The MCP server then pushes notifications/progress events to the client as messages arrive. The subscription terminates automatically when the session reaches a terminal phase (Completed or Failed).

RBAC required: sessions:get

Backed by: GET /api/ambient/v1/sessions/{id}/messages with Accept: text/event-stream

Input schema:

{
  "type": "object",
  "required": ["session_id"],
  "properties": {
    "session_id": {
      "type": "string",
      "description": "ID of the session to watch."
    },
    "after_seq": {
      "type": "integer",
      "description": "Deliver only messages with seq > after_seq. Default: 0 (replay all messages, then stream new ones)."
    }
  }
}

Return value:

{
  "subscription_id": "sub_abc123",
  "session_id": "3BEaN6kqawvTNUIXoSMcgOQvUDj"
}

Progress notification shape (pushed to client via notifications/progress):

{
  "method": "notifications/progress",
  "params": {
    "progressToken": "{subscription_id}",
    "progress": {
      "session_id": "3BEaN6kqawvTNUIXoSMcgOQvUDj",
      "message": {
        "id": "msg_xyz",
        "session_id": "3BEaN6kqawvTNUIXoSMcgOQvUDj",
        "seq": 42,
        "event_type": "TEXT_MESSAGE_CONTENT",
        "payload": "delta='Hello from the agent'",
        "created_at": "2026-03-21T10:01:00Z"
      }
    }
  }
}

Terminal notification (sent when session reaches Completed or Failed):

{
  "method": "notifications/progress",
  "params": {
    "progressToken": "{subscription_id}",
    "progress": {
      "session_id": "3BEaN6kqawvTNUIXoSMcgOQvUDj",
      "terminal": true,
      "phase": "Completed"
    }
  }
}

Behavior:

The MCP server opens an SSE connection to the backend for the given session
Messages received on the SSE stream are forwarded as notifications/progress events
The server polls session phase every 5 seconds; when Completed or Failed is observed, sends the terminal notification and closes the subscription
The client may call unwatch_session_messages at any time to cancel early

Errors:

Code	Condition
`SESSION_NOT_FOUND`	No session with that ID
`FORBIDDEN`	Token lacks `sessions:get`
`TRANSPORT_NOT_SUPPORTED`	Client is connected via stdio transport; streaming notifications require SSE

`unwatch_session_messages`

Cancels an active watch_session_messages subscription.

Input schema:

{
  "type": "object",
  "required": ["subscription_id"],
  "properties": {
    "subscription_id": {
      "type": "string",
      "description": "Subscription ID returned by watch_session_messages."
    }
  }
}

Return value:

{ "cancelled": true }

Errors:

Code	Condition
`SUBSCRIPTION_NOT_FOUND`	No active subscription with that ID

`list_agents`

Lists agents visible to the caller.

RBAC required: agents:list

Backed by: GET /api/ambient/v1/agents

Input schema:

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Search filter in SQL-like syntax (e.g. \"name like 'code-%'\"). Forwarded as the 'search' query parameter."
    },
    "page": {
      "type": "integer",
      "description": "Page number (1-indexed). Default: 1."
    },
    "size": {
      "type": "integer",
      "description": "Page size. Default: 20. Max: 100."
    }
  }
}

Return value: JSON-encoded AgentList.

{
  "kind": "AgentList",
  "page": 1,
  "size": 20,
  "total": 2,
  "items": [
    {
      "id": "agent-uuid-1",
      "name": "code-review",
      "owner_user_id": "user-uuid",
      "version": 3
    }
  ]
}

Note: Agent.prompt is write-only in the API. list_agents and get_agent do not return prompt text.

Errors:

Code	Condition
`UNAUTHORIZED`	Token invalid
`FORBIDDEN`	Token lacks `agents:list`

`get_agent`

Returns detail for a single agent by ID or name.

RBAC required: agents:get

Backed by: GET /api/ambient/v1/agents/{id} (by ID), or GET /api/ambient/v1/agents?search=name='{name}' (by name)

Input schema:

{
  "type": "object",
  "required": ["agent_id"],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent ID (UUID) or agent name. If the value does not parse as a UUID, it is treated as a name and resolved via search."
    }
  }
}

Return value: JSON-encoded Agent.

Errors:

Code	Condition
`AGENT_NOT_FOUND`	No agent matches the ID or name
`AMBIGUOUS_AGENT_NAME`	Name search returns more than one agent
`FORBIDDEN`	Token lacks `agents:get`

`create_agent`

Creates a new agent.

RBAC required: agents:create

Backed by: POST /api/ambient/v1/agents

Input schema:

{
  "type": "object",
  "required": ["name", "prompt"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Agent name. Must be unique for the owning user. Alphanumeric, hyphens, underscores only."
    },
    "prompt": {
      "type": "string",
      "description": "System prompt defining the agent's persona and behavior."
    }
  }
}

Return value: JSON-encoded Agent at version: 1.

Errors:

Code	Condition
`AGENT_NAME_CONFLICT`	An agent with this name already exists for the caller
`INVALID_REQUEST`	`name` contains disallowed characters or `prompt` is empty
`FORBIDDEN`	Token lacks `agents:create`

`update_agent`

Updates an agent's prompt. Creates a new immutable version (increments Agent.version). Prior versions are preserved.

RBAC required: agents:patch

Backed by: PATCH /api/ambient/v1/agents/{id}

Input schema:

{
  "type": "object",
  "required": ["agent_id", "prompt"],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent ID (UUID)."
    },
    "prompt": {
      "type": "string",
      "description": "New system prompt. Creates a new agent version."
    }
  }
}

Return value: JSON-encoded Agent at the new version number.

Errors:

Code	Condition
`AGENT_NOT_FOUND`	No agent with that ID
`FORBIDDEN`	Token lacks `agents:patch` or caller does not own the agent

`patch_session_annotations`

Merges key-value annotation pairs into a session's annotations field. Annotations are unrestricted user-defined string metadata — unlike labels they are not used for filtering, but they are readable by any agent or external system with sessions:get. This makes them a scoped, programmable state store: any application can write and read agent/session state without a custom database.

RBAC required: sessions:patch

Backed by: PATCH /api/ambient/v1/sessions/{id}

Input schema:

{
  "type": "object",
  "required": ["session_id", "annotations"],
  "properties": {
    "session_id": {
      "type": "string",
      "description": "ID of the session to update."
    },
    "annotations": {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Key-value annotation pairs to merge. Keys use reverse-DNS prefix convention (e.g. 'myapp.io/status'). Values are arbitrary strings up to 4096 bytes. Existing annotations not present in the patch are preserved. To delete an annotation, set its value to the empty string.",
      "example": {"myapp.io/status": "blocked", "myapp.io/blocker-id": "PROJ-1234"}
    }
  }
}

Return value: JSON-encoded updated Session.

Behavior:

Reads existing Session.annotations
Merges the provided annotations (provided keys overwrite existing values; empty-string values remove the key)
Writes back via PATCH /api/ambient/v1/sessions/{id}

Errors:

Code	Condition
`SESSION_NOT_FOUND`	No session with that ID
`ANNOTATION_VALUE_TOO_LARGE`	A value exceeds 4096 bytes
`FORBIDDEN`	Token lacks `sessions:patch`

`patch_agent_annotations`

Merges key-value annotation pairs into a ProjectAgent's annotations field. Agent annotations are persistent across sessions — they survive session termination and are visible to all future sessions for that agent. Use them to store durable agent state: last-known task, accumulated context index, external system IDs, etc.

RBAC required: agents:patch

Backed by: PATCH /api/ambient/v1/projects/{project_id}/agents/{agent_id}

Input schema:

{
  "type": "object",
  "required": ["project_id", "agent_id", "annotations"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project ID the agent belongs to."
    },
    "agent_id": {
      "type": "string",
      "description": "Agent ID (UUID) or agent name."
    },
    "annotations": {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Key-value annotation pairs to merge. Empty-string values remove the key.",
      "example": {"myapp.io/last-task": "PROJ-1234", "myapp.io/index-sha": "abc123"}
    }
  }
}

Return value: JSON-encoded updated ProjectAgent.

Errors:

Code	Condition
`AGENT_NOT_FOUND`	No agent with that ID or name
`ANNOTATION_VALUE_TOO_LARGE`	A value exceeds 4096 bytes
`FORBIDDEN`	Token lacks `agents:patch`

`patch_project_annotations`

Merges key-value annotation pairs into a Project's annotations field. Project annotations are the widest-scope state store — visible to every agent and session in the project. Use them for project-level configuration, feature flags, shared context, and cross-agent coordination state that outlives any single session.

RBAC required: projects:patch

Backed by: PATCH /api/ambient/v1/projects/{id}

Input schema:

{
  "type": "object",
  "required": ["project_id", "annotations"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project ID (UUID) or project name."
    },
    "annotations": {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Key-value annotation pairs to merge. Empty-string values remove the key.",
      "example": {"myapp.io/feature-flags": "{\"dark-mode\":true}", "myapp.io/release": "v2.3.0"}
    }
  }
}

Return value: JSON-encoded updated Project.

Errors:

Code	Condition
`PROJECT_NOT_FOUND`	No project with that ID or name
`ANNOTATION_VALUE_TOO_LARGE`	A value exceeds 4096 bytes
`FORBIDDEN`	Token lacks `projects:patch`

`list_projects`

Lists projects visible to the caller.

RBAC required: projects:list

Backed by: GET /api/ambient/v1/projects

Input schema:

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "description": "Page number (1-indexed). Default: 1."
    },
    "size": {
      "type": "integer",
      "description": "Page size. Default: 20. Max: 100."
    }
  }
}

Return value: JSON-encoded ProjectList.

`get_project`

Returns detail for a single project by ID or name.

RBAC required: projects:get

Backed by: GET /api/ambient/v1/projects/{id} (by ID), or GET /api/ambient/v1/projects?search=name='{name}' (by name)

Input schema:

{
  "type": "object",
  "required": ["project_id"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project ID (UUID) or project name."
    }
  }
}

Return value: JSON-encoded Project.

Errors:

Code	Condition
`PROJECT_NOT_FOUND`	No project matches the ID or name
`FORBIDDEN`	Token lacks `projects:get`

@mention Pattern

Syntax

A mention is any token in message text matching the pattern @{identifier}, where {identifier} matches [a-zA-Z0-9_-]+.

Multiple mentions in a single message are supported. Each resolves independently and spawns a separate child session.

Resolution Algorithm

Given @{identifier} in a push_message call:

If {identifier} matches UUID format ([0-9a-f-]{36}): call GET /api/ambient/v1/agents/{identifier}. If found, resolution succeeds.
Otherwise: call GET /api/ambient/v1/agents?search=name='{identifier}'. If exactly one result, resolution succeeds. If zero results, return MENTION_NOT_RESOLVED. If more than one result, return AMBIGUOUS_AGENT_NAME.

Delegation Behavior

For each successfully resolved mention:

The mention token is stripped from the prompt text. Example: @code-review please check this becomes please check this.
create_session is called with:
- project_id = same project as the calling session
- prompt = mention-stripped text
- agent_id = resolved agent ID
- parent_session_id = calling session ID
The child session is started immediately (same behavior as create_session).
The push_message response includes the child session in delegated_session.

Example

Calling session ID: sess-parent
Message text: "@code-review check the auth module for security issues"

Resolution:
  @code-review → GET /api/ambient/v1/agents?search=name='code-review'
               → agent ID: agent-abc123

Delegation:
  POST /api/ambient/v1/sessions
    { name: "check-auth-...", project_id: "demo-6640",
      prompt: "check the auth module for security issues",
      project_agent_id: "agent-abc123",
      parent_session_id: "sess-parent" }
  POST /api/ambient/v1/sessions/{new-id}/start

Response:
  {
    "message": { "id": "msg-xyz", "seq": 5, "event_type": "user", "payload": "@code-review check the auth module for security issues" },
    "delegated_session": { "id": "sess-child", "name": "check-auth-...", "phase": "Pending", ... }
  }

HTTP Endpoint (ambient-api-server Integration)

The ambient-api-server exposes the MCP server's SSE transport at:

GET  /api/ambient/v1/mcp/sse
POST /api/ambient/v1/mcp/message

Authentication: Authorization: Bearer {token} header. Required on all requests. The token is forwarded to the MCP server process as AMBIENT_TOKEN, which it uses for all backend API calls during the session.

Request flow:

Browser / MCP client
    │  GET /api/ambient/v1/mcp/sse
    │  Authorization: Bearer {token}
    ▼
ambient-api-server
    │  spawns or connects to mcp-server process
    │  injects AMBIENT_TOKEN={token}
    ▼
mcp-server (SSE mode)
    │  MCP JSON-RPC over SSE
    ▼
ambient-api-server REST API
    │  Authorization: Bearer {token}  ← same token, forwarded
    ▼
platform resources

Error codes:

HTTP Status	Condition
`401`	Missing or invalid bearer token
`403`	Token valid but lacks minimum required permissions
`503`	MCP server process could not be started

Sidecar Deployment

Platform MCP Sidecar (`ambient-mcp`)

Sessions opt into the platform MCP sidecar by setting the annotation:

ambient-code.io/mcp-sidecar: "true"

This annotation is set on the Session resource at creation time. The CP reads it and injects the ambient-mcp container into the runner Job pod.

Integration Credential Sidecars

For each credential bound to the session's Project (via CREDENTIAL_IDS), the CP injects an additional sidecar container running the corresponding MCP server. Each sidecar has its own isolated environment containing only its credential. The runner container has no integration credential tokens in its environment or filesystem.

Credential Provider	Sidecar Name	Image	Port	Env Vars Injected
`github`	`credential-github`	`ghcr.io/github/github-mcp-server` (via `mcp-proxy`)	`:8091`	`GITHUB_PERSONAL_ACCESS_TOKEN`, `AMBIENT_API_URL`, `AMBIENT_CP_TOKEN_URL`, `SESSION_ID`
`jira`	`credential-jira`	`mcp-atlassian` (native SSE)	`:8092`	`JIRA_URL`, `JIRA_API_TOKEN`, `JIRA_EMAIL`, `AMBIENT_API_URL`, `AMBIENT_CP_TOKEN_URL`, `SESSION_ID`
`kubeconfig`	`credential-k8s`	`kubernetes-mcp-server` (Go binary)	`:8093`	`KUBECONFIG` (file mount), `AMBIENT_API_URL`, `AMBIENT_CP_TOKEN_URL`, `SESSION_ID`
`google`	`credential-google`	`workspace-mcp` (init + run)	`:8094`	`GOOGLE_OAUTH_*`, `USER_GOOGLE_EMAIL`, `AMBIENT_API_URL`, `AMBIENT_CP_TOKEN_URL`, `SESSION_ID`

The runner connects to each sidecar as an SSE MCP client on http://localhost:{port}/sse.

Each credential sidecar receives AMBIENT_API_URL, AMBIENT_CP_TOKEN_URL, and SESSION_ID so it can re-fetch tokens from the backend API when credentials approach expiry. The sidecar authenticates to the backend using the same RSA-OAEP token exchange mechanism as the ambient-mcp sidecar.

When no credentials are bound to the Project, no credential sidecars are injected. The runner operates without integration credentials — this is the credential-free fallback.

Git Operations Without Token Exposure

The runner container has no git credential helper and no GitHub/GitLab tokens. The agent performs git operations exclusively through MCP tools:

Push commits: github-mcp → PushFiles tool (commits and pushes in one call)
Create PRs: github-mcp → CreatePullRequest tool
Clone repos: Init container (runs before the agent, has its own isolated credentials)

The agent SHOULD NOT use git push or gh pr create directly — these require tokens in the runner environment, which violates the isolation model. System prompts instruct the agent to use MCP tools for all git write operations.

Pod Layout

Job Pod (session-{id}-runner)
├── container: runner
│     Environment:
│       SESSION_ID, PROJECT_NAME, WORKSPACE_PATH, LLM_MODEL, ...
│       USE_VERTEX, ANTHROPIC_API_KEY or GOOGLE_APPLICATION_CREDENTIALS
│       AMBIENT_MCP_URL=http://localhost:8090
│       CREDENTIAL_MCP_URLS={"github":"http://localhost:8091", ...}
│     NO integration tokens: no GITHUB_TOKEN, JIRA_API_TOKEN, etc.
│     NO token files: no /tmp/.ambient_github_token, etc.
│     Connects to sidecars via SSE MCP on localhost ports
│
├── container: ambient-mcp
│     image: localhost/vteam_ambient_mcp:latest
│     MCP_TRANSPORT=sse, MCP_BIND_ADDR=:8090
│     AMBIENT_API_URL, AMBIENT_CP_TOKEN_URL, AMBIENT_CP_TOKEN_PUBLIC_KEY
│     SESSION_ID (for RSA-OAEP token exchange)
│
├── container: github-mcp          (only if github credential bound)
│     image: ghcr.io/github/github-mcp-server
│     GITHUB_PERSONAL_ACCESS_TOKEN={from backend API}
│     GITHUB_TOOLSETS=repos,issues,pull_requests,code_security
│     AMBIENT_API_URL, AMBIENT_CP_TOKEN_URL, SESSION_ID
│     Listens :8091 (SSE)
│
├── container: jira-mcp            (only if jira credential bound)
│     JIRA_URL, JIRA_API_TOKEN, JIRA_EMAIL
│     AMBIENT_API_URL, AMBIENT_CP_TOKEN_URL, SESSION_ID
│     Listens :8092
│
└── ... (additional credential sidecars as needed)

CLI Commands

The acpctl CLI gains a new subcommand group for interacting with the MCP server in development and testing contexts.

`acpctl mcp tools`

Lists all tools registered on the MCP server.

Flags: none

Behavior: Connects to the MCP server in stdio mode, sends tools/list, prints results, exits.

Example:

$ acpctl mcp tools
TOOL                      DESCRIPTION
list_sessions             List sessions with optional filters
get_session               Get full detail for a session by ID
create_session            Create and start a new agentic session
push_message              Send a user message to a running session
patch_session_labels      Merge labels into a session
watch_session_messages    Subscribe to a session's message stream
unwatch_session_messages  Cancel a message stream subscription
list_agents               List agents visible to the caller
get_agent                 Get agent detail by ID or name
create_agent              Create a new agent
update_agent              Update an agent's prompt (creates new version)
patch_session_annotations Merge annotations into a session (programmable state)
patch_agent_annotations   Merge annotations into an agent (durable state)
patch_project_annotations Merge annotations into a project (shared state)
list_projects             List projects visible to the caller
get_project               Get project detail by ID or name

Exit codes: 0 success, 1 connection failed, 2 auth error.

`acpctl mcp call <tool> [flags]`

Calls a single MCP tool and prints the result as JSON.

Flags:

Flag	Type	Description
`--input`	string	JSON-encoded tool input. Required.
`--url`	string	MCP server URL (SSE mode). If omitted, uses stdio mode against a locally started mcp-server binary.

Example:

$ acpctl mcp call list_sessions --input '{"phase":"Running"}'
{
  "kind": "SessionList",
  "total": 2,
  "items": [...]
}

$ acpctl mcp call push_message --input '{"session_id":"abc123","text":"@code-review check auth.go"}'
{
  "message": { "seq": 7, "event_type": "user", ... },
  "delegated_session": { "id": "sess-child", "phase": "Pending", ... }
}

Exit codes: 0 success, 1 tool returned error, 2 auth error, 3 tool not found.

Go SDK Example

Location: components/ambient-sdk/go-sdk/examples/mcp/main.go

This example demonstrates connecting to the MCP server via SSE and calling list_sessions and push_message. It is runnable against a live cluster.

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "os"

    mcp "github.com/mark3labs/mcp-go/client"
)

func main() {
    serverURL := os.Getenv("AMBIENT_MCP_URL") // e.g. http://localhost:8090
    token := os.Getenv("AMBIENT_TOKEN")

    client, err := mcp.NewSSEMCPClient(serverURL+"/sse",
        mcp.WithHeader("Authorization", "Bearer "+token),
    )
    if err != nil {
        log.Fatal(err)
    }
    ctx := context.Background()

    if err := client.Start(ctx); err != nil {
        log.Fatal(err)
    }

    _, err = client.Initialize(ctx, mcp.InitializeRequest{})
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.CallTool(ctx, mcp.CallToolRequest{
        Params: mcp.CallToolParams{
            Name:      "list_sessions",
            Arguments: map[string]any{"phase": "Running"},
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    var out any
    _ = json.Unmarshal([]byte(result.Content[0].Text), &out)
    b, _ := json.MarshalIndent(out, "", "  ")
    fmt.Println(string(b))
}

Error Catalog

Code	HTTP equivalent	Description
`UNAUTHORIZED`	401	Token missing, invalid, or expired
`FORBIDDEN`	403	Token valid but lacks required RBAC permission
`SESSION_NOT_FOUND`	404	No session with the given ID
`SESSION_NOT_RUNNING`	409	Operation requires session in Running phase
`AGENT_NOT_FOUND`	404	No agent matches the given ID or name
`AMBIGUOUS_AGENT_NAME`	409	Name search matched more than one agent
`PROJECT_NOT_FOUND`	404	No project matches the given ID or name
`MENTION_NOT_RESOLVED`	422	`@mention` token could not be matched to any agent
`INVALID_REQUEST`	400	Missing required field or malformed input
`INVALID_LABEL_KEY`	400	Label key contains `=` or whitespace
`INVALID_LABEL_VALUE`	400	Label value is empty
`AGENT_NAME_CONFLICT`	409	Agent name already exists for this owner
`SUBSCRIPTION_NOT_FOUND`	404	No active subscription with the given ID
`TRANSPORT_NOT_SUPPORTED`	400	Operation requires SSE transport; caller is on stdio
`ANNOTATION_VALUE_TOO_LARGE`	400	Annotation value exceeds 4096 bytes
`INTERNAL`	500	Backend returned an unexpected error

Spec Completeness Checklist

Per ambient-spec-development.md, this spec is complete when:

Uh oh!

FilesExpand file tree

mcp-server.spec.md

Latest commit

History

mcp-server.spec.md

File metadata and controls

Spec: Ambient Platform MCP Server

Overview

Component

Directory Structure

Configuration

MCP Protocol

Initialize

Transports

Error Format

Tool Definitions

list_sessions

get_session

create_session

push_message

patch_session_labels

watch_session_messages

unwatch_session_messages

list_agents

get_agent

create_agent

update_agent

patch_session_annotations

patch_agent_annotations

patch_project_annotations

list_projects

get_project

@mention Pattern

Syntax

Resolution Algorithm

Delegation Behavior

Example

HTTP Endpoint (ambient-api-server Integration)

Sidecar Deployment

Platform MCP Sidecar (ambient-mcp)

Integration Credential Sidecars

Git Operations Without Token Exposure

Pod Layout

CLI Commands

acpctl mcp tools

acpctl mcp call <tool> [flags]

Go SDK Example

Error Catalog

Spec Completeness Checklist

`list_sessions`

`get_session`

`create_session`

`push_message`

`patch_session_labels`

`watch_session_messages`

`unwatch_session_messages`

`list_agents`

`get_agent`

`create_agent`

`update_agent`

`patch_session_annotations`

`patch_agent_annotations`

`patch_project_annotations`

`list_projects`

`get_project`

Platform MCP Sidecar (`ambient-mcp`)

`acpctl mcp tools`

`acpctl mcp call <tool> [flags]`