---
name: add-mcp-from-catalog
description: Add a reviewed MCP Catalogue server to an explicit AICP project through the Speakeasy AI Control Plane Platform MCP.
---

# Add an MCP from the catalog

Use this workflow only through the authenticated Speakeasy AI Control Plane (AICP) Platform MCP. It follows the same guarded outcome a user would complete manually in the AICP dashboard: select a reviewed MCP, configure it for an explicit project, finish secure setup, and verify readiness. The package itself grants no organization access.

If the user instead supplies a remote MCP URL outside the reviewed catalogue, use the `add-mcp-from-remote-url` workflow.

## Safety rules

- Never ask the user to paste API keys, passwords, access or refresh tokens, OAuth codes, client secrets, secret headers, or MCP credentials into chat.
- Never ask the user to supply an MCP endpoint. Use the server-owned catalog candidate and registration workflow.
- Show non-secret provider and setup URLs only when a Platform MCP tool returns them.
- Keep the chosen project and catalog candidate explicit. Do not infer either from a previous conversation or silently substitute another target.
- Registration is private and does not distribute or publish the MCP.
- Use `send_platform_mcp_feedback` only after asking for consent, and never include identifiers, URLs, credentials, payloads, headers, logs, or attachments.

## Workflow

1. Call `list_projects` to verify that the Platform MCP is authenticated and obtain the eligible projects. If authenticated discovery is unavailable, stop and ask the user to complete or repair AICP OAuth; do not claim that installation succeeded.
2. Call `search_mcp_catalog`. Present the eligible projects and reviewed candidates, then ask the user to choose one exact project and one exact candidate.
3. Call `inspect_mcp_candidate` for the selected candidate. Explain the bounded change and collect only the non-secret configuration fields declared by that result.
4. After explicit confirmation, call `register_catalog_mcp` with the exact selected project, reviewed candidate, declared non-secret configuration, and a fresh idempotency key. Do not distribute it.
5. Call `get_mcp_readiness` with the returned project and registration ID to inspect persisted readiness.
6. Route secure setup from the exact readiness evidence:
   - For `upstream_identity_provider_not_configured`, explain that AICP can attach the one identity provider discovered from the persisted reviewed MCP source. Ask for explicit confirmation, then call `attach_platform_mcp_identity_provider`, present its exact Inspect authorization URL, and wait for the user to use Connect or Authorize.
   - For `upstream_authorization_required`, call `attach_platform_mcp_identity_provider` again with confirmation to retrieve the current server-issued Inspect authorization URL. Present that exact clickable URL and wait for the user to use Connect or Authorize.
   - For any other secure dashboard setup result, present only its exact server-returned setup URL. The user completes OAuth or secret entry outside the agent. Never request the resulting code, token, or secret in chat.
7. After the user completes any secure handoff, branch by caller surface:
   - For a connected external Platform MCP client, call `get_mcp_readiness` with `force: true`. Do not rely on stale or inferred readiness.
   - For a managed project assistant, call `get_mcp_readiness` without `force` and report only the persisted actor-scoped evidence. A forced provider probe stays with connected external clients; identity-provider attachment does not.
8. When readiness is current and ready, report the server-returned evidence. Registration is still private at this point: an MCP takes effect only once a plugin carries it.
9. Call `get_mcp_client_admission` for the same project and registration ID and report the mode it returns together with the custom client ID metadata URLs it lists, which together decide which MCP clients may authorize against this server. Change it only when the user asks: explain what the proposed mode admits and refuses, ask for explicit confirmation, then call `set_mcp_client_admission` with that exact mode and `confirmed: true`. Known clients (`presets`) refuses an unlisted client at authorization with no fallback, so confirm the user accepts that before selecting it. Custom client ID metadata URLs are still added from the MCP server's Authentication settings in the AICP dashboard.
10. Call `list_plugins` for the selected project, present the plugins it returns, and ask the user which one should carry this MCP. Do not choose for them and do not assume the default plugin.
11. After the user names a plugin, call `distribute_mcp_to_plugin` with that exact plugin. A name matching nothing is refused as `not_found` and a name matching more than one as `ambiguous_target`; report the refusal and ask again rather than retrying with a different plugin, creating a plugin, or distributing to another project.

OAuth consent and approved secret entry are the expected out-of-agent stops. Project and catalog selection and identity-provider attachment confirmation stay in the conversation.