--- name: add-mcp-from-remote-url description: Add a user-supplied remote MCP server URL to an explicit AICP project through the Speakeasy AI Control Plane Platform MCP. --- # Add an MCP from a remote URL Use this workflow only through the authenticated Speakeasy AI Control Plane (AICP) Platform MCP when the user supplies a remote MCP server URL that is not in the reviewed MCP Catalogue. It follows the same guarded outcome a user completes in the AICP dashboard: inspect the URL, confirm the bounded evidence and project, register privately, finish secure setup, and verify readiness. For a reviewed catalogue entry, use `add-mcp-from-catalog` instead. The package itself grants no organization access. ## 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. Authentication and headers are configured only through secure AICP dashboard setup. - Use `inspect_mcp_candidate` as the only read-only inspection step for a user-supplied URL. It returns bounded evidence and does not register or distribute anything. - Keep the target project explicit. Never infer it from a previous conversation or silently substitute another project. - Before registration, show the user the returned URL, transport, tool count and names, authentication posture, setup requirement, and OAuth-discovery state. State any missing evidence honestly. - Register only after the user explicitly confirms this exact remote server and project. Registration revalidates and re-inspects the URL; an earlier inspection is never trusted as admission evidence. - Registration is private. Do not claim the server is available to users until fresh readiness succeeds and exact-plugin distribution is rollout-enabled. - Show non-secret setup and authorization URLs only when a Platform MCP tool returns them. - 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 eligible projects. If discovery is unavailable, stop and ask the user to complete or repair AICP OAuth. 2. If the user names a product that could be in the reviewed catalogue, call `search_mcp_catalog` by name before handling the URL. Prefer an exact reviewed candidate when available. 3. Call `inspect_mcp_candidate` with `remote_url` set to the user's exact URL. Do not supply catalogue selectors at the same time. 4. Present the returned bounded evidence. Ask the user to explicitly confirm registering this exact URL in one exact project. If inspection reports an error or unavailable evidence, do not retry unchanged input or claim registration succeeded. Only when `create_project` is in your tool list, and no listed project fits or none exists yet, may you offer a new project. A managed project assistant has no `create_project` tool and always registers in its own project, so never offer it there. For a new project, agree its exact name and choose one idempotency key for this create; pass that same key on the preview and on the confirmed call. Call `create_project` with that name, that key, and `confirmed: false` to preview it: nothing is created, and the `confirmation_required` result returns the exact slug the project would get. Do not work the slug out yourself. Show that slug to the user as the project's permanent address in dashboard links; it does not change on rename. After the user confirms the name and slug, call `create_project` again with the same name, the same key, and `confirmed: true`, and use the project it returns. Use a fresh key only for a new attempt after a refusal. A `conflict` refusal means a project already holds that slug and nothing was created: offer that existing project or a different name. Creating a project needs organization administrator access; if it is refused, say so rather than choosing another project. Confirming the new project's name is not consent to register: once it exists, ask the user to confirm this exact URL in that exact new project before continuing. 5. After confirmation, call `register_remote_mcp` with the exact project, URL, optional safe display name, and a fresh idempotency key. This re-inspects the URL and creates private project configuration only. 6. If this workflow is running in a managed project assistant, present the returned dashboard setup URL when one exists, and call `get_mcp_readiness` without `force` to report the persisted, actor-scoped evidence. Never force a provider probe from an assistant. A freshly registered MCP normally has no persisted evidence yet and reports `readiness_unavailable`; that is not a reason to stop. Provider attachment does not depend on readiness evidence, but it does depend on the inspection's OAuth discovery evidence: attachment obtains a client from the provider automatically, through dynamic client registration or, when the provider supports it instead, a client ID metadata document. Only when inspection reported `authentication: authentication_required` with `oauth_discovery: available_dcr` or `oauth_discovery: available_cimd` (its `automatic_client_registration` is `dynamic_client_registration` or `client_id_metadata_document`), ask for explicit confirmation, call `attach_platform_mcp_identity_provider` with `confirmed: true`, present its exact authorization URL, and wait for the user to use Connect or Authorize there. Describe either path as automatic sign-in setup, not manual setup: the only remaining step is the user's own sign-in. When inspection reported `authentication_required` with `oauth_discovery: available` (`automatic_client_registration: none`), the provider advertises OAuth but neither dynamic registration nor client ID metadata documents, so do not attempt attachment; hand off to the dashboard setup URL, where the user configures a client registered with that provider or a Service Account credential. When inspection reported `authentication_required` with incomplete or absent OAuth discovery, the upstream expects a static credential such as an API key or Basic credential; do not attempt attachment, and tell the user to configure it as a Service Account credential through the dashboard setup URL, never in chat. When inspection reported `anonymous`, the endpoint needs no upstream identity provider — skip attachment and continue. 7. For an external Platform MCP client, if `next_action` is `secure_dashboard_setup_required`, present the exact `dashboard_setup_url`. The user completes authentication or secret entry outside chat; never request the resulting value. 8. For an external Platform MCP client, call `get_mcp_readiness` with the selected project and returned registration ID. For a non-ready result, follow only its server-provided repair action. When it requires provider attachment, ask for explicit confirmation before `attach_platform_mcp_identity_provider`, then present its exact authorization URL. 9. For an external Platform MCP client, after secure setup or authorization, call `get_mcp_readiness` with `force: true`. Do not rely on stale or inferred readiness. 10. For an external Platform MCP client, when readiness is current and ready, report the server-returned evidence. Registration remains private until a separately rollout-gated exact-plugin distribution is available. 11. 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. OAuth consent, secret entry, and provider authorization are the expected out-of-agent stops. URL and project selection, registration confirmation, and provider-attachment confirmation stay in the conversation.