MCP Server

The orchestrator embeds an MCP (Model Context Protocol) server that agent runtimes connect to as clients. This is how agents access platform capabilities — push notifications, user data, conversation history, artifacts, and workflows — without holding credentials.

How It Works

The MCP server is mounted at /mcp/v1 on the orchestrator. Agent runtimes connect via HTTP with Server-Sent Events (SSE) for streaming.

At startup, the runtime discovers available tools by calling ListTools on the MCP endpoint
During a conversation turn, the agent's LLM decides to call a tool
The runtime sends a tools/call request to the MCP server
The orchestrator authenticates, executes the tool, audits the call, and returns the result
The result is fed back into the LLM context

к сведению

No tool names are hardcoded in the runtime. All tools are discovered dynamically from the MCP server. Adding a new tool to the orchestrator makes it available to all runtimes without a pod restart.

Authentication

Every MCP request carries a Bearer token in the Authorization header:

Token format: Base64URL payload + HMAC-SHA256 signature
Payload: Encodes the calling user ID and workspace ID
Validation: Constant-time signature comparison on every request
Signing key: Shared between orchestrator and runtime via Kubernetes Secret

The orchestrator extracts the user and workspace identity from the token — tool handlers never need to parse auth themselves.

Tool Categories

The MCP server registers tools across 6 categories:

Push Notifications

Tool	Description
`send_push_notification`	Send a push notification to the user's mobile device

User Context

Tool	Description
`get_user_profile`	Fetch user name, email, nickname, and preferences
`get_workspace_info`	Get workspace details and agent list
`list_conversations`	List all conversations with titles and timestamps
`search_past_messages`	Search messages by keyword within conversations

Agent Collaboration

Tool	Description
`create_agent_history`	Record notable events in an agent's history log
`send_message_to_agent`	Send a message to another agent and get a response

Artifact Management

Tool	Description
`create_artifact`	Create a shared document or code artifact
`read_artifact`	Read artifact content with version history
`update_artifact`	Update artifact (optimistic locking via `expected_version`)
`review_artifact`	Review with outcome: approved, changes_requested, or commented

Workflow Engine

Tool	Description
`create_workflow`	Define a multi-step agent workflow
`trigger_workflow`	Start a workflow with optional initial context
`check_workflow_status`	Check workflow progress
`list_workflows`	List all workflow definitions

Memory Palace

19 tools for the memory system — see the Memory Palace Guide for full details.

Audit Logging

Every MCP tool call is logged to the database:

Tool name
Input arguments (capped at 4,096 bytes)
Output result (capped at 4,096 bytes)
User ID and workspace ID
Success/failure status
Duration in milliseconds

This audit trail is accessible via the agent history API and is used for compliance reporting.

Adding a New MCP Tool

Add a register* function in internal/orchestrator/server/mcp/ (e.g., tools_myfeature.go)
Call it from registerTools() in register.go
The tool receives *Deps with access to all services (DB, logger, signing key, MCPService, AuditService, drawer repo, KG, embedder, etc.)
Use sdkmcp.AddTool(server, toolDef, handler) to register
The runtime discovers the new tool automatically on next ListTools call

Source Files

File	Purpose
`internal/orchestrator/server/mcp/server.go`	MCP server creation, auth middleware, handler
`internal/orchestrator/server/mcp/register.go`	Tool registration orchestrator
`internal/orchestrator/server/mcp/deps.go`	Shared dependencies struct
`internal/orchestrator/server/mcp/tools_memory.go`	Memory Palace tools (19 tools)
`internal/orchestrator/server/mcp/tools_*.go`	Other tool categories

What's next: See the Agent Runtime Tools page for how tools are consumed by agents, or the gRPC Contracts for the streaming protocol.

How It Works​

Authentication​

Tool Categories​

Push Notifications​

User Context​

Agent Collaboration​

Artifact Management​

Workflow Engine​

Memory Palace​

Audit Logging​

Adding a New MCP Tool​

Source Files​