MCP Integration

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and call tools from external servers. Lifecycle supports MCP, so you can extend the AI Agent with tools beyond the built-in Kubernetes and GitHub capabilities.

When you register an MCP server, Lifecycle connects to it, discovers the available tools, caches their definitions, and makes them available during chat sessions. MCP tools appear alongside built-in tools and work the same way.

Configuring MCP servers

MCP server configurations are managed through the REST API. Each configuration includes these fields:

Transport auto-negotiation

Lifecycle automatically negotiates the transport protocol. It tries StreamableHTTP first, then falls back to SSE (Server-Sent Events). If both fail, the connection is rejected with an error describing what went wrong.

Connectivity validation

Lifecycle checks that the MCP server is reachable and returns at least one tool:

• On create — Validation always runs. If the server is unreachable or returns zero tools, the request fails with 422.
• On update — Validation only runs when url or headers change. If neither changes, the existing cached tools are preserved.

During validation, cachedTools is automatically populated with the tools discovered from the server.

Scoping and merge behavior

MCP servers can be scoped at two levels:

• Global (scope: "global") — Available to all repositories.
• Per-repository (scope: "myorg/myrepo") — Available only to that specific repository.

Runtime merge

When the AI Agent starts a session, Lifecycle resolves the effective set of MCP servers by combining:

1. All enabled global servers (minus any in the repository’s disabledSlugs list)
2. All enabled per-repository servers for that build’s repository

The combined list gives the agent the full set of MCP tools.

Disabling global servers per-repository

A repository can opt out of specific global MCP servers by adding their slugs to the disabledSlugs list. This prevents those servers from contributing tools for that repository without affecting others.

Managing MCP servers via API

All endpoints are under /api/v2/ai/config/mcp-servers. Request and response bodies use JSON. Header values are redacted to "******" in all responses.

List servers

Returns all MCP server configurations for the given scope. Defaults to "global" if scope is omitted.

Create a server

Registers a new MCP server. Lifecycle validates connectivity before saving.

Returns the created configuration (status 201) with redacted headers and populated cachedTools.

Get a server by slug

Returns a single configuration with redacted headers. Defaults to "global" scope. Returns 404 if not found.

Update a server

Only include the fields you want to change. If url or headers change, connectivity is re-validated.

Returns the updated configuration. Returns 404 if not found, 422 if connectivity validation fails.

Delete a server

Soft-deletes the configuration. Returns 204 on success, 404 if not found.

Health check

Checks connectivity for all enabled servers. Connects to each one, lists tools, and reports reachability. If the tool list changed since the last check, cached tools are automatically refreshed.

Tool naming and safety

Naming convention

To avoid collisions between servers, MCP tools are exposed with a namespaced name:

For example, a tool called lookup_user from a server with slug my-server becomes mcp__my-server__lookup_user. The agent handles this automatically.

Safety mapping

MCP tool annotations are mapped to Lifecycle safety levels that influence how the agent uses each tool:

Annotations are evaluated in priority order: destructiveHint takes precedence over readOnlyHint, which takes precedence over openWorldHint.

Error handling

MCP tool errors fall into three categories:

Recoverable errors let the agent retry or suggest alternatives. Protocol errors indicate a fundamental compatibility issue between Lifecycle and the server.

Troubleshooting

Server fails connectivity check

1. Check the URL — Confirm the URL is correct and reachable from the Lifecycle server.
2. Check the transport — Your server must support StreamableHTTP or SSE. Stdio-only servers do not work with Lifecycle.
3. Check authentication — If your server requires auth headers, make sure they are included in the headers field. Header values are redacted in responses, so you cannot read them back.
4. Check the timeout — If the server is slow to respond, increase the timeout value.

Tools not appearing in the agent

1. Verify the server returns at least one tool — Lifecycle rejects servers that expose zero tools during validation.
2. Check the enabled flag — Disabled servers are excluded from tool resolution.
3. Check the scope — A server scoped to a specific repo does not appear for builds in other repos.
4. Check disabledSlugs — A repo-level configuration may be opting out of your global server.

Health check shows unreachable

Run the health check endpoint to see the specific error message in the error field. Common causes include the server being down or network policies blocking traffic from Lifecycle pods.