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:

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:

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:

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:

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

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:

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:

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

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

For stdio:

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.

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