# MCP Server

WSO2 Agent Manager (AMP) ships a Model Context Protocol (MCP) server that lets MCP-capable AI assistants — Claude Code, Codex, Cursor, and others — drive the platform directly from the developer's terminal. Through the server, an assistant can list projects, register agents, trigger builds, and deploy images without leaving the conversation.

## Overview[​](#overview "Direct link to Overview")

The MCP server is exposed by `agent-manager-service` at the `/mcp` path on the public API URL. It speaks MCP over Streamable HTTP and is protected by the same OAuth 2.0 Authorization Code + PKCE flow that secures the rest of the AMP API, against the bundled Thunder identity provider.

A single OAuth client (`am-mcp`) is pre-registered in Thunder out of the box, so most users do not need to provision their own client to get started.

## Available Tools[​](#available-tools "Direct link to Available Tools")

The MCP server provides **12 tools** organized into four toolsets covering the agent lifecycle — from creating a project through deploying an agent. Trace, log, and metrics tools live on a separate server; see [Observer MCP Server](/agent-manager/docs/v1.0.0-alpha1/reference/observer-mcp-server/.md).

**Project Toolset (3 tools)**

* `list_projects` — List projects in an organization. Supports pagination via `limit` and `offset`.
* `create_project` — Create a new project (the logical container for agents and related resources).
* `list_project_agent_pairs` — Walk every project in the organization and return `(project, agent)` name pairs, with optional case-insensitive substring filters on project and agent names. Useful when an assistant needs to locate an agent without knowing which project it lives in.

**Agent Toolset (3 tools)**

* `list_agents` — List agents in a project. Each entry includes the provisioning type (`internal` or `external`) so the assistant can tell platform-hosted agents apart from externally-hosted ones.
* `create_external_agent` — Register an externally-hosted agent. Returns the agent identity, a long-lived API token, and language-specific zero-code instrumentation instructions (Python or Ballerina) the assistant can hand back to the user.
* `create_internal_agent_python` — Create a platform-hosted Python agent from a GitHub repository. Accepts repo URL, branch, app path, Python version, run command, interface type (`DEFAULT` chat-on-`/chat:8000` or `CUSTOM` with port + OpenAPI), environment variables, and an optional auto-instrumentation toggle. Creating the agent automatically triggers its initial build.

**Build Toolset (3 tools)**

Internal agents only — external agents are never built by the platform.

* `list_builds` — Paginated list of builds for an agent, including status, image ID, and timestamps. Includes a `retry_after_seconds` hint when a build is still in progress.
* `get_build_details` — Detailed view of a single build: steps, durations, commit, and build parameters.
* `build_agent` — Trigger a fresh build from a specific commit (defaults to the latest commit on the configured branch). Returns immediately — successful builds trigger deployment automatically, so the assistant only needs to poll `get_build_details` for completion.

**Deployment Toolset (3 tools)**

* `list_deployments` — An agent's deployments across all environments, keyed by environment name, with current state (`active`, `in-progress`, `failed`, `not-deployed`, or `suspended`) and image.
* `deploy_agent` — Deploy a built image to the lowest environment in the deployment pipeline. Accepts runtime environment variables (plain values, sensitive flags, or references to existing secrets) and an `enable_auto_instrumentation` toggle.
* `update_deployment_state` — Transition a deployment in a specific environment: `redeploy` (fresh rollout of the current deployment) or `undeploy` (remove the deployment from that environment).

## Finding the MCP Server URL[​](#finding-the-mcp-server-url "Direct link to Finding the MCP Server URL")

The MCP server URL follows the public URL of the `agent-manager-service`:

```
<server-public-url>/mcp
```

For a stock local installation (Quick Start, docker-compose, or k3d via the bundled Helm chart), the API is served through the OpenChoreo control-plane gateway at `api.amp.localhost:8080`, so the MCP server URL is:

```
http://api.amp.localhost:8080/mcp
```

If you have changed `serverPublicURL` (Helm) or `SERVER_PUBLIC_URL` (docker-compose), substitute that value.

## Default OAuth Client[​](#default-oauth-client "Direct link to Default OAuth Client")

AMP ships a pre-registered OAuth application in Thunder for MCP clients:

| Client ID | Grant Type                | Redirect URIs                                                        | Use Case                                                                                |
| --------- | ------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `am-mcp`  | Authorization Code + PKCE | `http://127.0.0.1:33418/callback`, `http://localhost:33418/callback` | Interactive use with AI assistants that support browser-based OAuth (Claude Code, etc.) |

The client is public (no secret), PKCE is required, and the callback port is pinned to **33418**. Because the redirect URIs are baked into the OAuth client registration, every MCP client must run its local OAuth listener on port `33418` to complete the login.

The `am-mcp` client is provisioned automatically by the `wso2-amp-thunder-extension` Helm chart (script `58-am-mcp-client.sh`) and is already wired into `KEY_MANAGER_AUDIENCE` on the docker-compose setup, so no manual registration is required for the default installations.

## Configuring AI Assistants[​](#configuring-ai-assistants "Direct link to Configuring AI Assistants")

The examples below assume the default local URL `http://api.amp.localhost:8080/mcp`. Replace it with your deployment's value if different.

### Claude Code[​](#claude-code "Direct link to Claude Code")

Register the MCP server with Claude Code using the `am-mcp` client and the pinned callback port:

```
claude mcp add --transport http agent-manager http://api.amp.localhost:8080/mcp \
  --client-id am-mcp \
  --callback-port 33418
```

* `--transport http` selects MCP Streamable HTTP transport.
* `--client-id am-mcp` matches the pre-registered Thunder OAuth client.
* `--callback-port 33418` pins Claude Code's local OAuth listener to the port registered as a redirect URI in Thunder.

Verify the registration from within a Claude Code session:

```
/mcp
```

The first tool call in any session opens a browser to the Thunder login page. Subsequent calls reuse the cached token until it expires; Claude Code refreshes it transparently.

### Codex[​](#codex "Direct link to Codex")

Codex CLI consumes MCP servers through its `~/.codex/config.toml` file. Because Codex's native MCP transport does not currently drive a browser-based OAuth flow, use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge Codex's stdio transport to the AMP server's HTTP endpoint — it will open the browser for OAuth on the first call and cache the token.

Add this block to `~/.codex/config.toml`:

```
[mcp_servers.agent-manager]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "http://api.amp.localhost:8080/mcp",
  "--client-id", "am-mcp",
  "--callback-port", "33418",
]
```

Restart Codex (or start a new session). On the first tool call, `mcp-remote` opens the Thunder login page; after authenticating, the token is cached under `~/.mcp-auth/` and reused until it expires.

tip

`mcp-remote` requires Node.js (and `npx`) on `PATH`. If you'd rather install the bridge globally instead of running it via `npx -y`, run `npm install -g mcp-remote` and replace `command = "npx"` / `args = ["-y", "mcp-remote@latest", ...]` with `command = "mcp-remote"` / `args = [...]`.

## Next Steps[​](#next-steps "Direct link to Next Steps")

* Try a few prompts in Claude Code, e.g. *"List the projects in my org"*, *"Create a new Python agent from this repo"*, *"Deploy the latest build of agent X"*.
* See [Observer MCP Server](/agent-manager/docs/v1.0.0-alpha1/reference/observer-mcp-server/.md) to let the same assistant inspect runtime logs, metrics, and traces for a deployed agent.
* See [Observe Your First Agent](/agent-manager/docs/v1.0.0-alpha1/tutorials/observe-first-agent/.md) for an end-to-end walkthrough of registering and instrumenting an agent — the same flow the MCP `create_external_agent` tool automates.