MCP Server

Zeta Alpha serves its tool layer to external agents over the Model Context Protocol (streamable HTTP). An external MCP client (Claude Code, Cursor, VS Code, Codex, an enterprise agent gateway, or your own application) lists and calls the tools of a named MCP server setup, authenticated as a platform user. Tools run with that user's entitlements, so document ACLs apply exactly as in the UI.

Endpoint

https://api.zeta-alpha.com/v0/service/mcp/<tenant>/?mcp_server_identifier=<identifier>

• The tenant is a path segment: OAuth discovery (RFC 9728) strips query strings, and the authorization server is resolved per tenant.
• mcp_server_identifier is required and names one of the tenant's setups. There is no default: a missing or unknown identifier is rejected.
• Per-installation deployments replace the host (https://api.<installation-domain>/v0/service/mcp/…).

Each setup's page in platform-admin shows its exact URL and copy-paste connection snippets per client.

Authentication

Mode	How	Identity
API key	X-Auth: <api key> header	The key's user
OAuth	Authorization: Bearer <token> via an OAuth client registered in platform-admin (Tenants → your tenant → OAuth clients)	The signed-in user

OAuth clients use authorization_code with PKCE S256 and come in two types:

• Desktop app: public client, no secret, for applications on users' machines. Loopback callbacks on any port are accepted, plus the fixed callbacks of claude.ai connectors, vscode.dev, and Cursor cloud.
• Web app: confidential client with a secret, for applications with their own backend (Copilot Studio, Bedrock AgentCore, a Zeta Alpha agent consuming this server). Its redirect URLs are registered at creation.

The server publishes RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource/v0/service/mcp/<tenant>/, so OAuth-capable clients discover the tenant's authorization server from the MCP URL alone. Dynamic Client Registration is not offered; pass the pre-registered client id (for example claude mcp add … --client-id <client id>). ChatGPT custom connectors support neither pre-registered clients nor API-key headers and cannot connect today. Codex connects with the API-key header; its OAuth sends a fixed client id and cannot use a pre-registered client.

Configuration: mcp_server_setups

A setup is a named tool bundle stored on the tenant (platform-admin → Tenants → your tenant → MCP Server Setups). It is not an agent: there are no instructions, no dispatch, no agent loop, only the capability configuration blocks that agents also use. Tools that make LLM calls themselves select a model by name through the model policy (see below).

{
  "mcp_server_identifier": "research",
  "configuration": {
    "tools_provider_configuration": {
      "enabled": true,
      "include_sources": ["tag_tools"]
    },
    "memory_provider_configuration": {
      "enabled": true,
      "writable_source": "memory_notes"
    },
    "memory_note_memory_store_configuration": {
      "enabled": true
    }
  }
}

tools_provider_configuration

Controls which registered tool sources and tools the setup exposes.

Field	Default	Meaning
enabled	true	Serve Python-defined tools from registered sources.
include_sources	none	Source names to force-enable, regardless of each source's own flag.
exclude_sources	none	Denylist of source names; always wins.
include_tools	all	Allowlist of individual tool names.
exclude_tools	none	Denylist of individual tool names; wins over includes.

Every source defaults off, so an empty configuration serves no tools. A source is active when it is named in include_sources, or when its own <source>_source_configuration block sets enabled: true; exclude_sources vetoes either. Source blocks also carry source-specific settings (e.g. index_tools_source_configuration with the index description and known filters), the same blocks documented in configuring capabilities.

memory_provider_configuration

Exposes the memory write tools (save_memory, update_memory), keyed to the authenticated user.

Field	Default	Meaning
enabled	false	Enable the memory system.
writable_source	first registered store	source_name of the store writes go to.
include_sources	all	Allowlist of memory store source names.

Each memory store is enabled by its own block; the built-in notes-backed store is memory_note_memory_store_configuration (enabled, include_scopes, default ["own"]) and registers under the source name memory_notes.

skills_provider_configuration

Exposes the skill tools: use_skill (activate a skill and read its instructions), skill content and resource readers, create_skill, and skill editing, backed by the registered skill sources and keyed to the authenticated user.

Field	Default	Meaning
enabled	true	Enable the skills system.
injection_mode	both	prompt disables the tools; over MCP only the tools half applies.
include_sources	none	Skill source names to force-enable, regardless of each source's own flag.
exclude_sources	none	Denylist of skill source names; always wins.
writable_source	first registered source	Source new skills are written to.

Skill sources follow the same rule as tool sources: all off by default, activated by include_sources or their own <source>_skills_source_configuration block.

llm_selection_configuration

Selects the named LLM configuration (an entry in the tenant's llm_configurations) that LLM-using tools in the bundle run on:

"llm_selection_configuration": { "llm_configuration_name": "gpt-5.2" }

When the setup pins no name, the caller may select one per request with ?llm_configuration_name=<name> on the MCP URL. A pinned name cannot be overridden by the query parameter; an unpinned setup accepts any name in the tenant's llm_configurations. With no selection in scope, LLM-using tools stay listed and answer that they are unavailable when called; tools that need no LLM are unaffected.

Consuming from a Zeta Alpha agent

Our own agents consume external MCP servers (including this one) through mcp_tools_provider_configuration, see connecting MCP servers.

Local development

za mcp serves the same engine over the tools registered in your own project, see How to Serve Tools over MCP.