Manage MCP Access

Manage MCP access

Use this workflow only through the authenticated Speakeasy AI Control Plane (AICP) Platform MCP. It mirrors the guarded dashboard workflow for giving one explicitly selected organization member access to one explicitly selected configured MCP through a custom role. Installing the package grants no organization or project access.

Safety rules

• Never infer the project, MCP, custom role, member, or access rules from prior context. Present the eligible choices and require the user to select each target explicitly.
• Show members only by the masked identities returned by list_access_members. Never reconstruct, request, or reveal an unmasked identity.
• Do not expose raw identifiers or opaque references merely to distinguish choices. Present product names and masked identities; retain tool-returned selectors internally and use them only with the exact choice they represent.
• Assign only a role whose returned type is custom and whose fresh get_mcp_access coverage reports assignment_eligible: true. Eligibility means the entire role contains only exact mcp:connect selectors for the selected project and MCP; non-MCP, broad, other-project, other-MCP, or unknown grants are not eligible.
• Assigning a role includes all of its grants, not just the user's intended subset. Require explicit confirmation of ALL selected MCP grants by presenting EVERY assignment_rules entry from fresh get_mcp_access coverage. Each entry has all_tools and may have tool or disposition: all_tools: true means unrestricted tool access, including future tools, not merely the current catalogue. Explain each named tool and disposition rule, including future tools matching that disposition. Do not rely on allowed_known_tools to establish the full scope. Missing or incomplete assignment_rules is a stop condition, even when eligibility is true. Do not mutate or narrow a shared existing role to make it assignable; offer to create a dedicated narrow role instead.
• Stop when member results are suppressed, ambiguous, expired, or do not contain the selected masked identity. Ask the user for a different identity query rather than guessing.
• Stop if incomplete tool catalogue or unevaluated evidence prevents confirmation of exact scope. Never treat missing tools, tools_truncated: true, or unevaluated_grants: true as proof of narrow access.
• Local role and membership reads describe local desired state only. Never claim provider synchronization has converged or that the member has effective provider access based on local reads, mutation success, or receipt replay.
• If any read reports that the capability is unavailable, stop without claiming a change.

Workflow

1. Call list_projects with limit: 100. This tool supports only limit (capped at 100), not cursor or search. If truncated: true, stop and hand off project selection to the AICP dashboard; do not invent pagination or treat the partial list as complete. Otherwise present eligible project names and ask the user to choose one exact project. Keep its returned selector internal.
2. Call find_mcp for only that project with limit: 100. For an unfiltered list, follow next_cursor using cursor with the same project and no query until the list is complete. Cursor pagination is supported only for unfiltered results: never combine query and cursor. If a search result is truncated, narrow the query or switch to project-scoped unfiltered pagination. Stop if a complete, unambiguous choice cannot be established. Present configured MCP names and ask the user to choose one exact MCP. Keep its returned selector internal.
3. Call get_mcp_access for the selected project and MCP. Explain its authorization mode, known tool catalogue, and current local role coverage. If it is not managed by role-based access, stop; this workflow must not imply that assigning a role will take effect. Check catalogue completeness and unevaluated evidence before proposing any mutation; if exact scope cannot be confirmed, stop and use the dashboard rather than guessing.
4. Call list_access_roles. Present role names, types, privacy-safe member counts, and relevant MCP access summaries. Ask the user to choose an eligible existing custom role or explicitly choose to create a new custom role.
5. Resolve the custom role without silently broadening it:
   • For a new role, collect its name, optional description, and exact MCP access rules from the selected MCP's current enumerable tools or supported disposition classes. Explain the full scope, including any disposition-based access to future tools. Show all proposed grants and ask for explicit confirmation, then call create_mcp_access_role for the exact project and rules.
   • For an existing custom role, compare its complete coverage from get_mcp_access with the user's requested outcome and require assignment_eligible: true. If it grants a broader outcome, is ineligible, or exact scope cannot be confirmed, do not assign it or call update_mcp_access_role to narrow or repurpose it. Offer to create a dedicated narrow role with a separately confirmed scope. Otherwise make no role mutation and explicitly confirm all grants, not merely the intended subset.
   • Use fresh tool-returned opaque references and any required freshness or retry fields only as agent-operational inputs. Do not describe those mechanics as part of the user-facing outcome.
6. After role creation, call both list_access_roles and get_mcp_access again. Continue only if the selected custom role exists, reports assignment_eligible: true, and the re-read shows exactly all confirmed grants for the selected MCP. If the state conflicts or is incomplete, stop and report that no member assignment will be attempted.
7. Ask the user for an identity search of at least three characters, then call list_access_members without a role filter. Present only the returned masked identities and current role names. Require the user to choose one exact masked member; do not accept an unmasked identity or select on their behalf.
8. Immediately before assignment, refresh list_access_roles, get_mcp_access, and list_access_members for the exact prior choices. Keep the original identity query without a role filter so the privacy cohort is unchanged. Confirm internally that the project, MCP, custom role, all grants, assignment_eligible: true, and masked member still match. If a selector expired or the choices changed, present the safe names and masked identities again and ask the user to reselect. Stop on suppressed results or incomplete scope evidence.
9. Summarize the proposed local desired state using only the project name, MCP name, custom role name, masked member identity, and ALL selected MCP grants. Present EVERY assignment_rules entry in product language for final confirmation, distinguishing unrestricted future-tool access from the known catalogue list. Explain that existing member roles are preserved and provider synchronization remains unverified. Ask for one final explicit confirmation of that complete assignment, not just the user's intended subset.
10. After confirmation, call assign_mcp_access_role using only the exact refreshed custom-role and member choices, the explicit project, selected mcp_id, and confirmed: true. Pass the selected role's version from the immediately preceding get_mcp_access response as expected_role_version, and the selected member's version from the immediately preceding list_access_members response as expected_version. Supply a stable idempotency_key for retries of that exact request. Keep these fields internal. A version conflict requires fresh role and member reads, explicit reselection, and renewed confirmation before submitting a new request. Do not retry with another member, role, MCP, or project after a refusal or conflict.
11. The mutation response's snapshot_scope: assignment_commit identifies a historical snapshot of committed local desired state, including on receipt replay. Never reuse its member version for a new write. Verify current local state rather than treating that snapshot as final proof:
    • Call list_access_roles again and confirm the selected role's current local state.
    • Call get_mcp_access again and confirm the role remains eligible and still has exactly all confirmed grants for the selected MCP.
    • Call list_access_members again with the original identity query without a role filter. Preserve the original privacy cohort; do not filter by the newly assigned role. Confirm the selected masked member is listed with that role when privacy-safe enumeration is available.
    • If member enumeration is suppressed or any evidence is stale, incomplete, or inconsistent, report local verification as incomplete. Never bypass suppression by changing filters or infer membership from counts.
12. Report the selected project, MCP, custom role, masked member, and confirmed grants as committed local desired state only when supported by the evidence. Clearly separate the historical commit from current local verification and pending or unverified provider synchronization. These tools do not verify provider convergence or effective provider access; do not claim either from their local results.

Project, MCP, custom-role, masked-member, complete-grant, and final assignment choices all remain explicit conversation checkpoints. All selectors and mutation-control fields remain agent-operational.