Configure Private MCP Access

Configure private access for an existing MCP

Use the authenticated Speakeasy AI Control Plane (AICP) Platform MCP. Installing a plugin does not grant organization access, network access, or authorization to change an MCP. This workflow changes the address or network mode of an existing MCP server (including a hosted toolset) or gateway, not its upstream URL, its plugin membership, or its users' permissions. Hosted toolset network mode is managed through its canonical MCP server target; its address remains toolset-owned and must be changed in the dashboard.

1. Call list_projects and ask the administrator to select an exact project. The list caps at 100; if truncated, use the AICP dashboard to select the project rather than assuming the first page is complete.
2. Call list_plugins for that project and ask which existing plugin is affected. Call get_plugin for that exact plugin. Follow membership_next_cursor until all its members are listed. If a membership changes mid-pagination, restart. Preserve each typed target ID; do not guess an MCP from a display name or substitute a different server for a hosted toolset's canonical MCP server.
3. Ask the administrator to choose the exact MCP server or gateway. Call get_mcp_connection_settings with its project_id, target_kind, and target_id. Explain the current endpoints, network mode, configured ingress and plugin memberships. These are settings and observations, not evidence that a tailnet or client can connect. Stop if the target is ambiguous, unproxied, hidden, or the private address cannot be resolved safely.
4. If changing an address, use the dashboard for hosted toolsets. For other targets, ask which existing endpoint should move or whether to create a new endpoint, and which slug and existing custom domain to use. Present the exact before and after address, including whether changing domains clears an existing root alias. Never silently take another root alias, create a custom domain, alter backend IDs, or add the target to a plugin.
5. If changing network access, call get_mcp_network_traffic for the selected project_id and target_id with window: "7d". For its target_kind, use mcp for an MCP server or gateway for a gateway (connection settings instead uses mcp_server or gateway). Report observed public and private request counts and last-seen times before proposing the exact transition among public_only, dual, and private_only. Counts cover only observed requests while telemetry was enabled: zero does not prove a route is unused or that every client has migrated. If traffic reporting is unavailable, say so and require an independent client inventory before cutting off either route. Explain that private_only can break public clients, while dual retains public access. A private mode requires the server's admission and ingress readiness checks; do not infer readiness from a configured DNS name alone.
6. Immediately before each change, refresh get_mcp_connection_settings for the same exact target. Explain the proposed change and ask for explicit confirmation. Call set_mcp_address or set_mcp_network_access only after confirmation, with the fresh version as expected_version and a stable idempotency_key for that exact request. On conflict or refusal, re-read and request confirmation again. Never silently retry with a different target or value.
7. Treat the mutation receipt as evidence of the historical committed change, not of publication. Read get_mcp_connection_settings again to check current settings. Call get_plugin for every affected plugin and compare its publication evidence and desired package addresses. An enqueued request is not a published package; fresh: null is unknown, and fresh: false means the package needs a refresh. Read fresh together with last_publish: queued, running, or retrying means an update is already on its way, so read get_plugin again later instead of republishing; failed with failure_category: repository_conflict cannot be fixed by republishing, so do not retry it and send the administrator to Speakeasy support; last_publish.unavailable: true means the attempt could not be read, so do not infer a failure; if the publication evidence reports not_configured: true, no publish has ever been recorded and republish_plugin would refuse it, so send the administrator to the dashboard or Speakeasy support instead of offering it. If the package still reports fresh: false without an update on its way or a repository conflict, and the administrator wants it refreshed now, explain that republishing regenerates every plugin in the project, ask for explicit confirmation, then call republish_plugin with the exact project_id selected in step 1, that exact plugin, confirmed: true, and a stable idempotency_key. If the outcome is already_current, report that the package is already current and that no publish was requested. If it is enqueued, it is only a request that can be accepted before its run starts: treat it as pending until last_publish.requested_at is later than the republish or the publication evidence reports fresh: true (a republish can fold into a run already in flight without moving requested_at), read get_plugin again later before reporting the package as current, and never treat an older failed or succeeded attempt as the new request failing or being missed, or republish again because of it. If republish_plugin refuses: for not_configured, report that no package repository is connected and present the returned Plugins link; for not_found or ambiguous_target, ask the user for the exact plugin and do not hand off to the dashboard; for rate_limited, say nothing changed and do not retry automatically. If emission is disabled, the best-effort signal fails, the tool is unavailable, or the package cannot be verified, say so plainly and use the dashboard. Do not claim installed clients have refreshed or OAuth sessions have reconnected.
8. Report the exact MCP and plugin, the current configured address and mode, whether the generated package would use the private address, whether stored published fingerprints are current, and what the administrator must do to test tailnet connectivity and refresh clients. Keep operational selectors, version hashes, idempotency keys, and receipts out of the user-facing summary.