{ "schemaVersion": "1.0", "title": "Use AIP through MCP", "description": "Use this guide to connect an existing MCP client to getaip-server, inspect the projected surface, and call one native AIP capability through a stable facade tool. The same AIP gateway validates and dispatches the resulting action; the MCP l", "canonical": "https://getaip.org/docs/guides/use-aip-through-mcp", "route": "/docs/guides/use-aip-through-mcp", "source": "docs/guides/use-aip-through-mcp.md", "protocol": "Agent Interoperability Protocol", "protocolVersion": "1.0", "section": "Build with AIP", "documentType": "Guide", "language": "en", "revision": { "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635", "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb", "basis": "frontmatter" }, "downloads": { "md": "/docs/download/guides/use-aip-through-mcp.md", "txt": "/docs/download/guides/use-aip-through-mcp.txt", "json": "/docs/download/guides/use-aip-through-mcp.json", "pdf": "/docs/download/guides/use-aip-through-mcp.pdf" }, "content": { "format": "text/markdown", "markdown": "---\ntitle: Use AIP through MCP\ndescription: Connect an MCP client to getaip-server and invoke a stable AIP capability through Streamable HTTP or stdio\nkind: how-to\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Use AIP through MCP\n\nUse this guide to connect an existing MCP client to `getaip-server`, inspect the\nprojected surface, and call one native AIP capability through a stable facade\ntool. The same AIP gateway validates and dispatches the resulting action; the\nMCP layer translates the client request at the profile boundary.\n\nThe walkthrough first uses an unauthenticated loopback endpoint for local\ndevelopment. It then shows the separate controls required for a protected\nnetwork endpoint. It does not qualify a deployment, an identity provider, or\nan independent MCP client.\n\nThe examples target source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. This authoring pass checked the\nsource and command syntax without building the workspace or starting a\nservice.\n\n## Choose MCP or native AIP\n\nUse MCP when an editor, agent host, or automation client already implements\nMCP and needs a compatible view of AIP capabilities. Use native AIP when the\nclient needs direct access to the complete AIP message, lifecycle, identity,\nand transport contract.\n\n| Client need | Preferred path |\n|---|---|\n| Discover and call AIP capabilities from an MCP host | MCP profile |\n| Launch one local server process from an editor | MCP over stdio |\n| Connect a network client with resumable server events | MCP over Streamable HTTP |\n| Send native envelopes or use the complete AIP operational API | Native AIP |\n| Depend on an AIP guarantee that the selected MCP version cannot express | Native AIP, or an explicitly documented facade tool |\n\nMCP tool metadata alone does not grant AIP approval, transaction, retry, or\ndelivery guarantees. Read the capability contract returned by AIP before\ndepending on those semantics.\n\n## Choose a transport and version\n\nThe client and server negotiate one protocol version during MCP\ninitialization. The current implementation intentionally exposes this matrix:\n\n| MCP transport | `2024-11-05` | `2025-03-26` | `2025-06-18` | `2025-11-25` |\n|---|:---:|:---:|:---:|:---:|\n| stdio | Yes | Yes | Yes | Yes |\n| Legacy HTTP+SSE | Yes | No | No | No |\n| Streamable HTTP | No | Yes | Yes | Yes |\n\nStreamable HTTP uses `GET`, `POST`, and `DELETE` on `/mcp`. The aliases\n`/mcp/v1` and `/aip/v1/mcp` expose the same handler. Legacy compatibility uses\n`GET /mcp/legacy/sse` and `POST /mcp/legacy/messages` and is limited to\n`2024-11-05`.\n\nIf the requested version cannot run on the selected transport, the server\nselects the newest mutually supported executable version. Version-specific\nmethods remain unavailable when the selected version does not define them.\nFor example, task methods are available only with `2025-11-25`.\n\n## Prerequisites\n\nFor the loopback walkthrough, you need:\n\n- the reviewed source checkout and its locked Rust dependencies;\n- `curl` and `jq` for the explicit verification steps;\n- local TCP port `18080`, or another unused loopback port used consistently;\n- permission to create `.getaip-server-mcp-guide` in the checkout;\n- two terminals, one for `getaip-server` and one for the client commands.\n\nDo not expose the development command on a non-loopback interface. It bypasses\nHTTP authentication intentionally.\n\n## 1. Start a loopback Streamable HTTP endpoint\n\nFrom the repository root, start `getaip-server`:\n\n```sh\ncargo run --locked -p getaip-server -- \\\n --bind 127.0.0.1:18080 \\\n --service-id agent:getaip:server:mcp-guide \\\n --storage-dir .getaip-server-mcp-guide \\\n --allow-insecure-development\n```\n\nKeep this process running. In the second terminal, wait until the daemon\nreports that the gateway and required workers are ready:\n\n```sh\ncurl -fsS http://127.0.0.1:18080/ready \\\n | jq -e '.status == \"ready\"'\n```\n\nA successful check prints `true`. The `/ready` result is readiness for this\nprocess and configuration. It is not connector qualification or evidence that\nan external product is reachable.\n\n## 2. Inspect the projected surface\n\nInitialize a Streamable HTTP session and inspect the MCP peer:\n\n```sh\ncargo run --locked -p getaip-cli -- mcp inspect \\\n --url http://127.0.0.1:18080/mcp \\\n | jq -e '\n .compatibility.mcp.protocol_version == \"2025-11-25\"\n and any(.capabilities[]; .name == \"aip_capabilities\")\n and any(.capabilities[]; .name == \"aip_call\")\n '\n```\n\nThe command initializes the client, lists the MCP surface, and prints an AIP\nmanifest reconstructed by the outbound client bridge. A successful check\nprints `true`.\n\nCapability IDs in this reconstructed manifest use bridge-local IDs derived\nfrom the client configuration and MCP tool name. They are not the original\nnative AIP capability IDs. Use `aip_capabilities` or the native manifest when\nyou need stable native identity.\n\n## 3. Discover and call a stable AIP capability\n\nAsk the stable facade for the native daemon health capability:\n\n```sh\ncargo run --locked -p getaip-cli -- mcp call-tool aip_capabilities \\\n --url http://127.0.0.1:18080/mcp \\\n --arguments '{\n \"capability_id\": \"cap:aip:server:health\",\n \"include_schemas\": false,\n \"include_contracts\": true,\n \"include_bindings\": false\n }' \\\n | jq -e '\n .isError == false\n and any(\n .structuredContent.capabilities[];\n .id == \"cap:aip:server:health\"\n )\n '\n```\n\nThe returned contract identifies this operation as a read with synchronous\nexecution support. Invoke it through `aip_call` by native capability ID:\n\n```sh\ncargo run --locked -p getaip-cli -- mcp call-tool aip_call \\\n --url http://127.0.0.1:18080/mcp \\\n --arguments '{\n \"capability_id\": \"cap:aip:server:health\",\n \"input\": {}\n }' \\\n | jq -e '\n .isError == false\n and .structuredContent.status == \"ok\"\n and .structuredContent.protocol == \"AIP\"\n '\n```\n\nA successful call prints `true`. The local manifest also maps this capability\nto the generated MCP tool name `getaip_server_health`. Treat that name as a projection,\nnot as the stable native identity. The facade pair `aip_capabilities` and\n`aip_call` remains usable when a tenant connector-fleet catalog replaces the\ngenerated per-capability tool list.\n\n## 4. Use stdio for a command-launched client\n\nChoose stdio when the MCP host owns the `getaip-server` child process. After building\nthe release binary, verify the same projection directly:\n\n```sh\ncargo run --locked -p getaip-cli -- mcp inspect \\\n --command ./target/release/getaip-server \\\n --arg=--mcp-stdio \\\n --arg=--service-id \\\n --arg=agent:getaip:server:mcp-stdio \\\n --arg=--storage-dir \\\n --arg=.getaip-server-mcp-stdio\n```\n\nConfigure another MCP host with the same command and ordered argument list.\nUse an absolute executable and state path when the host does not start in the\nrepository directory. MCP host configuration field names vary, but the child\nprocess boundary uses these values:\n\n| Field | Value |\n|---|---|\n| Command | Absolute path to the reviewed `getaip-server` binary |\n| Arguments | `--mcp-stdio`, `--service-id`, one canonical service principal, and deployment-owned storage options |\n| Framing | One JSON-RPC frame per line on standard input and output |\n| HTTP credentials | Not applicable to the stdio boundary |\n\nThe stdio transport uses one process-owned session. The spawning host is the\ntrust boundary; HTTP bearer tokens and browser Origin checks do not apply.\nUse `--mcp-principal` and repeated `--mcp-principal-scope` values when the host\nneeds a more specific AIP actor than the deployment default. Restart a host\nthat caches command configuration or initialization state.\n\n## 5. Check client compatibility\n\nRun the outbound MCP client conformance checks against the loopback endpoint:\n\n```sh\ncargo run --locked -p getaip-cli -- mcp conformance \\\n --url http://127.0.0.1:18080/mcp\n```\n\nOr check the command boundary:\n\n```sh\ncargo run --locked -p getaip-cli -- mcp conformance \\\n --command ./target/release/getaip-server \\\n --arg=--mcp-stdio \\\n --arg=--service-id \\\n --arg=agent:getaip:server:mcp-conformance\n```\n\nThe command exits unsuccessfully when its client-conformance report contains a\nfailure. A passing report covers the tested client path and negotiated\ncontract. It does not establish production readiness, independent-client\ninteroperability, connector qualification, or live-product behavior.\n\n## Understand the projected surface\n\n`aip-profile-mcp` owns MCP data transfer objects and their AIP mappings. It\ndoes not own HTTP state, subprocesses, or the AIP runtime. Separate session,\nserver, client, and transport components enforce those boundaries.\n\nThe current `getaip-server` composition exposes stable AIP facade tools and, without a\nfleet catalog, generated tools for local capabilities. Other MCP families are\navailable only when both the negotiated version and installed provider support\nthem:\n\n| Surface | Current boundary |\n|---|---|\n| Stable AIP facade tools | Advertised by `getaip-server`; calls pass through the native gateway and runtime |\n| Generated capability tools | Derived from the local manifest; disabled when the fleet catalog owns discovery |\n| Resources | Metadata can come from the manifest; content reads require a resource provider |\n| Prompts and completions | Advertised only when their providers supply entries |\n| Roots, sampling, and elicitation | Depend on negotiated client capability and a real peer/provider path |\n| Logging | Supported by the current server composition |\n| Tasks | Advertised only for `2025-11-25` when task support is enabled |\n| Dynamic list notifications | Emitted when the installed projection source changes |\n\nDo not infer provider availability from the MCP schema vocabulary alone. An\nempty list or unsupported-method response can be correct for a deployment that\nhas not installed that provider.\n\n## Understand sessions and replay\n\nStreamable HTTP initialization creates or accepts a session ID and returns the\nselected version in response headers. Later `POST` requests carry that session\nID and the negotiated protocol version. `GET /mcp` opens the server stream,\nand `DELETE /mcp` closes the session and its replay state.\n\nThe server binds the session to the authenticated actor and optional verified\ntenant. Another identity cannot take over the ID. Tool arguments cannot select\nthe actor because the server constructs trusted execution context before it\ncalls the AIP gateway.\n\nTwo persistence boundaries must remain distinct:\n\n- MCP session snapshots use the configured runtime profile store, which can be\n PostgreSQL, durable local storage, or memory;\n- Streamable HTTP SSE replay retains at most 1,024 events per session and is\n file-backed only when `--storage-dir` is set.\n\nPostgreSQL runtime storage alone does not persist the SSE replay log. A client\ncan send `Last-Event-ID` on `GET /mcp` to replay retained events before the\nlive stream continues. This is bounded reconnect support, not an unlimited AIP\nevent archive.\n\n## Protect a production HTTP endpoint\n\nThe local bypass is unavailable on a public listener. A production MCP\nendpoint uses protected-resource metadata and RFC 7662 token introspection.\nThe following command shows the MCP-specific controls in context; complete\nstorage, edge, observability, backup, and rollout design belongs in the\nproduction deployment guide.\n\n```sh\ncargo run --locked -p getaip-server -- \\\n --bind 0.0.0.0:18080 \\\n --public-base-url https://aip.example.com \\\n --service-id agent:getaip:server:production \\\n --postgres-url-file /run/secrets/getaip-server-postgres-url \\\n --storage-dir /var/lib/getaip-server \\\n --mcp-resource https://aip.example.com/mcp \\\n --mcp-authorization-server https://identity.example.com \\\n --mcp-scope aip.invoke \\\n --mcp-required-scope aip.invoke \\\n --mcp-introspection-url https://identity.example.com/oauth2/introspect \\\n --mcp-introspection-issuer https://identity.example.com \\\n --mcp-introspection-client-id getaip-server \\\n --mcp-introspection-client-secret-file /run/secrets/mcp-introspection-secret \\\n --mcp-allowed-origin https://app.example.com\n```\n\nTerminate TLS at a trusted edge or deployment platform and route the public\nHTTPS origin to the private listener. The configured public base URL must use\nHTTPS for a non-loopback bind.\n\nBefore exposing the route, verify these controls:\n\n- the resource identifier matches the token audience and published endpoint;\n- the introspection issuer is one of the advertised authorization servers;\n- the token is active, unexpired, and contains every required scope;\n- the token subject parses as a canonical AIP principal;\n- any tenant used for routing comes from the verified token, not tool input;\n- every browser Origin is explicitly allowed; loopback origins remain the only\n implicit browser exception;\n- the database URL and introspection client secret are readable only from\n their deployment-owned secret files.\n\nPass an access token to `getaip` with `--bearer-token` or the\n`GETAIP_MCP_BEARER_TOKEN` environment variable. Prefer a secret-injection\nmechanism that does not persist the token in shell history. Static\n`--mcp-bearer-token` authentication on the server is restricted to explicit\ninsecure development and is not a production alternative to introspection.\n\n## Resolve common failures\n\n| Symptom | Likely boundary | Safe next check |\n|---|---|---|\n| `401 Unauthorized` | HTTP authentication | Confirm the endpoint is not using the loopback bypass, then check introspection activity, issuer, audience, expiry, and required scopes |\n| Browser request is rejected before authentication | Origin policy | Compare the exact request Origin with repeated `--mcp-allowed-origin` values |\n| Session ID is not found | Ownership or deletion | Reinitialize with the same authenticated identity; do not reuse an ID after `DELETE` |\n| Protocol version is rejected | Transport/version mismatch | Select a version marked for the chosen transport in the matrix above |\n| `aip_capabilities` omits a connector capability | Catalog visibility | Check verified tenant context, fleet admission, catalog revision, filters, and pagination cursor |\n| Generated tool disappeared after fleet enablement | Discovery mode changed | Use `aip_capabilities` and `aip_call` with the stable native capability ID |\n| Resource, prompt, or completion list is empty | Provider is absent | Verify that the deployment installed and populated the matching provider |\n| Reconnect cannot replay an older event | Replay boundary | Check `--storage-dir`, the 1,024-event bound, session ownership, and `Last-Event-ID` |\n| Call completed but an AIP lifecycle view is missing | Client used only the tool result | Query the appropriate stable facade lifecycle tool or use native AIP observation APIs |\n\nDo not retry a mutating call merely because the MCP connection ended. First\nlook up the AIP action using its stable action or idempotency identity. A lost\nresponse can leave the execution outcome unknown.\n\n## Stop and clean up the local walkthrough\n\nStop `getaip-server` with `Control-C`. Inspect the two local state directories before\nremoving only the walkthrough data:\n\n```sh\ndu -sh .getaip-server-mcp-guide .getaip-server-mcp-stdio 2>/dev/null || true\nrm -rf -- .getaip-server-mcp-guide .getaip-server-mcp-stdio\n```\n\nDo not apply this cleanup command to a production state path. It removes local\nruntime state and any file-backed MCP replay retained under those directories.\n\n## Related documentation\n\n- [Use native AIP](use-native-aip.md)\n- [Use the Rust SDK](use-rust-sdk.md)\n- [Profiles and connectors](../concepts/profiles-and-connectors.md)\n- [Actions and sessions](../concepts/actions-and-sessions.md)\n- [Identity and trust](../concepts/identity-and-trust.md)\n", "text": "Use AIP through MCP\n\nUse this guide to connect an existing MCP client to getaip-server, inspect the\nprojected surface, and call one native AIP capability through a stable facade\ntool. The same AIP gateway validates and dispatches the resulting action; the\nMCP layer translates the client request at the profile boundary.\n\nThe walkthrough first uses an unauthenticated loopback endpoint for local\ndevelopment. It then shows the separate controls required for a protected\nnetwork endpoint. It does not qualify a deployment, an identity provider, or\nan independent MCP client.\n\nThe examples target source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. This authoring pass checked the\nsource and command syntax without building the workspace or starting a\nservice.\n\nChoose MCP or native AIP\n\nUse MCP when an editor, agent host, or automation client already implements\nMCP and needs a compatible view of AIP capabilities. Use native AIP when the\nclient needs direct access to the complete AIP message, lifecycle, identity,\nand transport contract.\n\n| Client need | Preferred path |\n\n| Discover and call AIP capabilities from an MCP host | MCP profile |\n| Launch one local server process from an editor | MCP over stdio |\n| Connect a network client with resumable server events | MCP over Streamable HTTP |\n| Send native envelopes or use the complete AIP operational API | Native AIP |\n| Depend on an AIP guarantee that the selected MCP version cannot express | Native AIP, or an explicitly documented facade tool |\n\nMCP tool metadata alone does not grant AIP approval, transaction, retry, or\ndelivery guarantees. Read the capability contract returned by AIP before\ndepending on those semantics.\n\nChoose a transport and version\n\nThe client and server negotiate one protocol version during MCP\ninitialization. The current implementation intentionally exposes this matrix:\n\n| MCP transport | 2024-11-05 | 2025-03-26 | 2025-06-18 | 2025-11-25 |\n\n| stdio | Yes | Yes | Yes | Yes |\n| Legacy HTTP+SSE | Yes | No | No | No |\n| Streamable HTTP | No | Yes | Yes | Yes |\n\nStreamable HTTP uses GET, POST, and DELETE on /mcp. The aliases\n/mcp/v1 and /aip/v1/mcp expose the same handler. Legacy compatibility uses\nGET /mcp/legacy/sse and POST /mcp/legacy/messages and is limited to\n2024-11-05.\n\nIf the requested version cannot run on the selected transport, the server\nselects the newest mutually supported executable version. Version-specific\nmethods remain unavailable when the selected version does not define them.\nFor example, task methods are available only with 2025-11-25.\n\nPrerequisites\n\nFor the loopback walkthrough, you need:\n• the reviewed source checkout and its locked Rust dependencies;\n• curl and jq for the explicit verification steps;\n• local TCP port 18080, or another unused loopback port used consistently;\n• permission to create .getaip-server-mcp-guide in the checkout;\n• two terminals, one for getaip-server and one for the client commands.\n\nDo not expose the development command on a non-loopback interface. It bypasses\nHTTP authentication intentionally.\n1. Start a loopback Streamable HTTP endpoint\n\nFrom the repository root, start getaip-server:\n\ncargo run --locked -p getaip-server -- \\\n --bind 127.0.0.1:18080 \\\n --service-id agent:getaip:server:mcp-guide \\\n --storage-dir .getaip-server-mcp-guide \\\n --allow-insecure-development\n\nKeep this process running. In the second terminal, wait until the daemon\nreports that the gateway and required workers are ready:\n\ncurl -fsS http://127.0.0.1:18080/ready \\\n | jq -e '.status == \"ready\"'\n\nA successful check prints true. The /ready result is readiness for this\nprocess and configuration. It is not connector qualification or evidence that\nan external product is reachable.\n2. Inspect the projected surface\n\nInitialize a Streamable HTTP session and inspect the MCP peer:\n\ncargo run --locked -p getaip-cli -- mcp inspect \\\n --url http://127.0.0.1:18080/mcp \\\n | jq -e '\n .compatibility.mcp.protocolversion == \"2025-11-25\"\n and any(.capabilities[]; .name == \"aipcapabilities\")\n and any(.capabilities[]; .name == \"aipcall\")\n '\n\nThe command initializes the client, lists the MCP surface, and prints an AIP\nmanifest reconstructed by the outbound client bridge. A successful check\nprints true.\n\nCapability IDs in this reconstructed manifest use bridge-local IDs derived\nfrom the client configuration and MCP tool name. They are not the original\nnative AIP capability IDs. Use aipcapabilities or the native manifest when\nyou need stable native identity.\n3. Discover and call a stable AIP capability\n\nAsk the stable facade for the native daemon health capability:\n\ncargo run --locked -p getaip-cli -- mcp call-tool aipcapabilities \\\n --url http://127.0.0.1:18080/mcp \\\n --arguments '{\n \"capabilityid\": \"cap:aip:server:health\",\n \"includeschemas\": false,\n \"includecontracts\": true,\n \"includebindings\": false\n }' \\\n | jq -e '\n .isError == false\n and any(\n .structuredContent.capabilities[];\n .id == \"cap:aip:server:health\"\n )\n '\n\nThe returned contract identifies this operation as a read with synchronous\nexecution support. Invoke it through aipcall by native capability ID:\n\ncargo run --locked -p getaip-cli -- mcp call-tool aipcall \\\n --url http://127.0.0.1:18080/mcp \\\n --arguments '{\n \"capabilityid\": \"cap:aip:server:health\",\n \"input\": {}\n }' \\\n | jq -e '\n .isError == false\n and .structuredContent.status == \"ok\"\n and .structuredContent.protocol == \"AIP\"\n '\n\nA successful call prints true. The local manifest also maps this capability\nto the generated MCP tool name getaipserverhealth. Treat that name as a projection,\nnot as the stable native identity. The facade pair aipcapabilities and\naipcall remains usable when a tenant connector-fleet catalog replaces the\ngenerated per-capability tool list.\n4. Use stdio for a command-launched client\n\nChoose stdio when the MCP host owns the getaip-server child process. After building\nthe release binary, verify the same projection directly:\n\ncargo run --locked -p getaip-cli -- mcp inspect \\\n --command ./target/release/getaip-server \\\n --arg=--mcp-stdio \\\n --arg=--service-id \\\n --arg=agent:getaip:server:mcp-stdio \\\n --arg=--storage-dir \\\n --arg=.getaip-server-mcp-stdio\n\nConfigure another MCP host with the same command and ordered argument list.\nUse an absolute executable and state path when the host does not start in the\nrepository directory. MCP host configuration field names vary, but the child\nprocess boundary uses these values:\n\n| Field | Value |\n\n| Command | Absolute path to the reviewed getaip-server binary |\n| Arguments | --mcp-stdio, --service-id, one canonical service principal, and deployment-owned storage options |\n| Framing | One JSON-RPC frame per line on standard input and output |\n| HTTP credentials | Not applicable to the stdio boundary |\n\nThe stdio transport uses one process-owned session. The spawning host is the\ntrust boundary; HTTP bearer tokens and browser Origin checks do not apply.\nUse --mcp-principal and repeated --mcp-principal-scope values when the host\nneeds a more specific AIP actor than the deployment default. Restart a host\nthat caches command configuration or initialization state.\n5. Check client compatibility\n\nRun the outbound MCP client conformance checks against the loopback endpoint:\n\ncargo run --locked -p getaip-cli -- mcp conformance \\\n --url http://127.0.0.1:18080/mcp\n\nOr check the command boundary:\n\ncargo run --locked -p getaip-cli -- mcp conformance \\\n --command ./target/release/getaip-server \\\n --arg=--mcp-stdio \\\n --arg=--service-id \\\n --arg=agent:getaip:server:mcp-conformance\n\nThe command exits unsuccessfully when its client-conformance report contains a\nfailure. A passing report covers the tested client path and negotiated\ncontract. It does not establish production readiness, independent-client\ninteroperability, connector qualification, or live-product behavior.\n\nUnderstand the projected surface\n\naip-profile-mcp owns MCP data transfer objects and their AIP mappings. It\ndoes not own HTTP state, subprocesses, or the AIP runtime. Separate session,\nserver, client, and transport components enforce those boundaries.\n\nThe current getaip-server composition exposes stable AIP facade tools and, without a\nfleet catalog, generated tools for local capabilities. Other MCP families are\navailable only when both the negotiated version and installed provider support\nthem:\n\n| Surface | Current boundary |\n\n| Stable AIP facade tools | Advertised by getaip-server; calls pass through the native gateway and runtime |\n| Generated capability tools | Derived from the local manifest; disabled when the fleet catalog owns discovery |\n| Resources | Metadata can come from the manifest; content reads require a resource provider |\n| Prompts and completions | Advertised only when their providers supply entries |\n| Roots, sampling, and elicitation | Depend on negotiated client capability and a real peer/provider path |\n| Logging | Supported by the current server composition |\n| Tasks | Advertised only for 2025-11-25 when task support is enabled |\n| Dynamic list notifications | Emitted when the installed projection source changes |\n\nDo not infer provider availability from the MCP schema vocabulary alone. An\nempty list or unsupported-method response can be correct for a deployment that\nhas not installed that provider.\n\nUnderstand sessions and replay\n\nStreamable HTTP initialization creates or accepts a session ID and returns the\nselected version in response headers. Later POST requests carry that session\nID and the negotiated protocol version. GET /mcp opens the server stream,\nand DELETE /mcp closes the session and its replay state.\n\nThe server binds the session to the authenticated actor and optional verified\ntenant. Another identity cannot take over the ID. Tool arguments cannot select\nthe actor because the server constructs trusted execution context before it\ncalls the AIP gateway.\n\nTwo persistence boundaries must remain distinct:\n• MCP session snapshots use the configured runtime profile store, which can be\n PostgreSQL, durable local storage, or memory;\n• Streamable HTTP SSE replay retains at most 1,024 events per session and is\n file-backed only when --storage-dir is set.\n\nPostgreSQL runtime storage alone does not persist the SSE replay log. A client\ncan send Last-Event-ID on GET /mcp to replay retained events before the\nlive stream continues. This is bounded reconnect support, not an unlimited AIP\nevent archive.\n\nProtect a production HTTP endpoint\n\nThe local bypass is unavailable on a public listener. A production MCP\nendpoint uses protected-resource metadata and RFC 7662 token introspection.\nThe following command shows the MCP-specific controls in context; complete\nstorage, edge, observability, backup, and rollout design belongs in the\nproduction deployment guide.\n\ncargo run --locked -p getaip-server -- \\\n --bind 0.0.0.0:18080 \\\n --public-base-url https://aip.example.com \\\n --service-id agent:getaip:server:production \\\n --postgres-url-file /run/secrets/getaip-server-postgres-url \\\n --storage-dir /var/lib/getaip-server \\\n --mcp-resource https://aip.example.com/mcp \\\n --mcp-authorization-server https://identity.example.com \\\n --mcp-scope aip.invoke \\\n --mcp-required-scope aip.invoke \\\n --mcp-introspection-url https://identity.example.com/oauth2/introspect \\\n --mcp-introspection-issuer https://identity.example.com \\\n --mcp-introspection-client-id getaip-server \\\n --mcp-introspection-client-secret-file /run/secrets/mcp-introspection-secret \\\n --mcp-allowed-origin https://app.example.com\n\nTerminate TLS at a trusted edge or deployment platform and route the public\nHTTPS origin to the private listener. The configured public base URL must use\nHTTPS for a non-loopback bind.\n\nBefore exposing the route, verify these controls:\n• the resource identifier matches the token audience and published endpoint;\n• the introspection issuer is one of the advertised authorization servers;\n• the token is active, unexpired, and contains every required scope;\n• the token subject parses as a canonical AIP principal;\n• any tenant used for routing comes from the verified token, not tool input;\n• every browser Origin is explicitly allowed; loopback origins remain the only\n implicit browser exception;\n• the database URL and introspection client secret are readable only from\n their deployment-owned secret files.\n\nPass an access token to getaip with --bearer-token or the\nGETAIPMCPBEARERTOKEN environment variable. Prefer a secret-injection\nmechanism that does not persist the token in shell history. Static\n--mcp-bearer-token authentication on the server is restricted to explicit\ninsecure development and is not a production alternative to introspection.\n\nResolve common failures\n\n| Symptom | Likely boundary | Safe next check |\n\n| 401 Unauthorized | HTTP authentication | Confirm the endpoint is not using the loopback bypass, then check introspection activity, issuer, audience, expiry, and required scopes |\n| Browser request is rejected before authentication | Origin policy | Compare the exact request Origin with repeated --mcp-allowed-origin values |\n| Session ID is not found | Ownership or deletion | Reinitialize with the same authenticated identity; do not reuse an ID after DELETE |\n| Protocol version is rejected | Transport/version mismatch | Select a version marked for the chosen transport in the matrix above |\n| aipcapabilities omits a connector capability | Catalog visibility | Check verified tenant context, fleet admission, catalog revision, filters, and pagination cursor |\n| Generated tool disappeared after fleet enablement | Discovery mode changed | Use aipcapabilities and aipcall with the stable native capability ID |\n| Resource, prompt, or completion list is empty | Provider is absent | Verify that the deployment installed and populated the matching provider |\n| Reconnect cannot replay an older event | Replay boundary | Check --storage-dir, the 1,024-event bound, session ownership, and Last-Event-ID |\n| Call completed but an AIP lifecycle view is missing | Client used only the tool result | Query the appropriate stable facade lifecycle tool or use native AIP observation APIs |\n\nDo not retry a mutating call merely because the MCP connection ended. First\nlook up the AIP action using its stable action or idempotency identity. A lost\nresponse can leave the execution outcome unknown.\n\nStop and clean up the local walkthrough\n\nStop getaip-server with Control-C. Inspect the two local state directories before\nremoving only the walkthrough data:\n\ndu -sh .getaip-server-mcp-guide .getaip-server-mcp-stdio 2>/dev/null || true\nrm -rf -- .getaip-server-mcp-guide .getaip-server-mcp-stdio\n\nDo not apply this cleanup command to a production state path. It removes local\nruntime state and any file-backed MCP replay retained under those directories.\n\nRelated documentation\n• Use native AIP (use-native-aip.md)\n• Use the Rust SDK (use-rust-sdk.md)\n• Profiles and connectors (../concepts/profiles-and-connectors.md)\n• Actions and sessions (../concepts/actions-and-sessions.md)\n• Identity and trust (../concepts/identity-and-trust.md)\n" }, "integrity": { "algorithm": "sha256", "sourceDigest": "cf88971cdd7ba9efc62edd5d8dd5eea231d720e88ab7c44ae586e15b6f7c7de8" } }