Add MCP From Remote URL

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.