# Use AIP through MCP

AIP exposes its native capabilities to MCP clients without running a separate
business runtime. MCP requests enter the same gateway, use the same handlers,
and produce the same durable actions, policy decisions, events, and receipts as
native AIP requests.

Use this path when an existing editor, agent host, or automation platform already
speaks MCP. Use native AIP when the client needs the full operational and
enterprise lifecycle directly.

## Supported MCP Transports

| Transport | Endpoint or command | Use case |
|---|---|---|
| Streamable HTTP | `POST`, `GET`, and `DELETE /mcp` | Network clients and durable sessions |
| stdio | `aipd --mcp-stdio` | Command-launched clients such as editors |
| Legacy HTTP+SSE | `/mcp/legacy/sse` and `/mcp/legacy/messages` | MCP `2024-11-05` compatibility |

Aliases `/mcp/v1` and `/aip/v1/mcp` expose the same Streamable HTTP service.

The compatibility profile supports stable versions `2024-11-05`,
`2025-03-26`, `2025-06-18`, and `2025-11-25`. Version-specific method and
transport rules are negotiated during initialization.

## Connect a Streamable HTTP Client

Start a local daemon:

```sh
cargo run -p aipd -- \
  --bind 127.0.0.1:18080 \
  --service-id agent:aipd:mcp-local \
  --storage-dir .aipd-mcp-state \
  --allow-insecure-development
```

Point the MCP client to:

```text
http://127.0.0.1:18080/mcp
```

`--allow-insecure-development` is accepted only for a loopback development
listener. A production MCP endpoint must authenticate sessions.

## Connect a Command-Based Client

When `aipd` is installed, configure the MCP host with:

```text
command: aipd
arguments: --mcp-stdio --service-id agent:aipd:mcp-stdio
```

From a source checkout, configure `cargo` as the command, set the working
directory to the repository root, and pass:

```text
run -q -p aipd -- --mcp-stdio --service-id agent:aipd:mcp-stdio
```

The repository's `tools/aipd-mcp-stdio.sh` is a local deployment fixture with
machine-specific defaults; it is not the portable installation interface.

A host process normally reads MCP configuration when its session starts.
Changing the command or environment may require restarting that host. Ordinary
AIP connector and capability changes do not require changing MCP registration
when the stable command and endpoint remain the same.

## Inspect the Projected Surface

```sh
cargo run -p aipctl -- mcp inspect \
  --url http://127.0.0.1:18080/mcp
```

This initializes an MCP session, discovers tools/resources/prompts, and prints
their AIP manifest projection.

Call a tool through the outbound MCP client bridge:

```sh
cargo run -p aipctl -- mcp call-tool aipd_health \
  --url http://127.0.0.1:18080/mcp \
  --arguments '{}'
```

Tool names are profile projections. Native AIP code should use the stable
capability id from the manifest.

## What Is Projected

The MCP compatibility subsystem supports tools, resources, prompts,
completions, logging, roots, sampling, elicitation, cancellation, progress,
notifications, and task views. MCP objects are translated at the profile
boundary; MCP DTOs do not enter `aip-core`.

Native semantics that MCP cannot express directly are preserved in AIP state
and exposed through AIP facade tools and structured metadata where the MCP
version permits it. A client should not infer that a plain MCP tool descriptor
provides transaction or approval guarantees unless the projected contract says
so.

## Session and Replay Behavior

Streamable HTTP initialization establishes an MCP session owner. Subsequent
requests must use the negotiated protocol version and session id. `GET /mcp`
opens the server stream, `Last-Event-ID` requests retained replay, and
`DELETE /mcp` terminates the session.

When `aipd` has durable storage, retained SSE events survive daemon restart.
Replay remains bounded by deployment retention policy; it is not an unlimited
event archive.

## Protect a Production MCP Endpoint

For a static protected endpoint, configure a bearer token and resource
metadata. For OAuth deployments, configure protected-resource metadata and RFC
7662 introspection:

```sh
cargo run -p aipd -- \
  --bind 0.0.0.0:18080 \
  --service-id agent:aipd:production \
  --postgres-url "$AIP_POSTGRES_URL" \
  --mcp-resource https://aip.example.com/mcp \
  --mcp-authorization-server https://identity.example.com \
  --mcp-required-scope aip.invoke \
  --mcp-introspection-url https://identity.example.com/oauth2/introspect \
  --mcp-introspection-issuer https://identity.example.com \
  --mcp-introspection-client-id aipd \
  --mcp-introspection-client-secret-file /run/secrets/mcp-introspection-secret
```

Terminate TLS at a trusted edge or in the deployment platform. Restrict browser
origins explicitly. The token subject and scopes must map to an AIP principal;
they must not be replaced by principal fields supplied in tool arguments.

## Run Compatibility Checks

```sh
cargo run -p aipctl -- mcp conformance \
  --url http://127.0.0.1:18080/mcp
```

For stdio:

```sh
cargo run -p aipctl -- mcp conformance \
  --command aipd \
  --arg=--mcp-stdio \
  --arg=--service-id \
  --arg=agent:aipd:mcp-conformance
```

These checks validate the local compatibility contract. Release qualification
also requires the versioned fixture matrix and independent client/server
interoperability described in [Conformance](../reference/conformance.md).

## Troubleshooting

| Symptom | Check |
|---|---|
| Client cannot see new tools | Fetch the native manifest, then restart only the MCP host if it cached initialization |
| `401 Unauthorized` | Token, introspection result, required scopes, and resource audience |
| Session id rejected | Initialization completed, owner identity matches, and the session was not deleted |
| Protocol version rejected | Client selected one of the supported stable versions |
| Reconnect misses events | Durable storage, retention window, and `Last-Event-ID` value |
| Tool call works but no enterprise lifecycle is visible | Use the AIP facade tools or native operational APIs to query action state |