The management MCP server is an OAuth-protected endpoint at /mcp on your deployment that lets a coding agent inspect and change your Chickpea workspace. Where Admin is the browser door and @Chickpea is the Slack door, this is the door for a client you already run. This page covers connecting a client, the tools it gets, how confirmation works, and how to take access away.
The management MCP and Chickpea’s Slack tools are adapters over one management service. Neither owns separate permissions or mutation rules.
Prerequisites
- A deployment past setup. The OAuth endpoints under
/api/authreturn404until Slack is connected and the deployment is healthy. - An HTTPS origin. Chickpea derives the MCP resource from the deployment origin and rejects anything but HTTPS, except loopback for local development. The endpoint is mounted on both Cloudflare and Node.
- An active Chickpea membership. Slack OIDC is the only human sign-in. No passwords. Guests, Slack Connect users, bots, and deactivated Slack accounts are never provisioned, so they cannot authorize a client.
- A client that speaks OAuth 2.1. It must discover protected-resource metadata, register as a public PKCE client, and follow a browser redirect. Chickpea’s contract tests cover Codex CLI and Desktop, Claude Code, and MCP Inspector; they verify the protocol, not any particular installed build.
Connect the client
Add the server
In your client, add a remote or custom MCP server and give it your deployment URL ending in /mcp:
https://<your-deployment>/mcpDo not create or paste a bearer token. Chickpea issues its own.
Let the client register itself
The client reads /.well-known/oauth-protected-resource/mcp, which names the exact /mcp resource and /api/auth as its authorization server. If it holds no client ID yet, it registers at /api/auth/oauth2/register.
Chickpea accepts public clients only: a token_endpoint_auth_method of none, a native or web application type, authorization_code with an optional refresh_token grant, a single code response type, at most 10 redirect URIs that are exact HTTPS or loopback URLs, and chickpea:workspace as the only scope. Wildcards, remote HTTP redirects, client keys, and metadata over 16 KiB are rejected. Registration is rate limited, and a burst returns 429 with registration_rate_limited.
Sign in with Slack
The client opens the authorization URL in a browser. Chickpea stores an opaque one-use continuation, sends you to Sign in with Slack, and resumes only that server-created path. Slack OIDC is the human proof of who you are.
Allow workspace management
Chickpea then shows Allow workspace management?, naming the client and the one permission it asks for, chickpea:workspace. Choose Allow. The client exchanges the code with PKCE and reconnects with a short-lived, resource-bound access token.
Verify
Ask the client to call inspect_workspace. It returns your current non-secret Agents, skills, connections, repositories, channels, and provider availability, plus team authority if you are an Owner. Nothing changes, so this is safe to run first.
Two failures are worth telling apart:
401with a protected-resource challenge. The client sent no token, or an invalid one. Reconnect it.403. Authorization worked, but your live Chickpea membership, role, or scope no longer permits the request.
What you can do
The server advertises itself as chickpea-workspace, contract version 2.5.0, with 17 tools. The first nine read; the rest write.
| Tool | What it does |
|---|---|
inspect_workspace |
Current non-secret Agents, skills, connections, repositories, channels, provider availability, and Owner-only team authority |
prepare_connector_setup |
A browser handoff URL for connecting one catalog service to one editable Agent |
discover_slack_channels |
Channels in the connected Slack workspace, before publishing an Agent |
test_mcp_connection |
Tests one saved Agent MCP connection and returns a sanitized result plus discovered tools |
inspect_memory |
The single memory body owned by one Agent |
inspect_routines |
Schedules and their safely projected content |
export_workspace_recipe |
Selected Agents and their connection requirements as a versioned, secret-free recipe |
preview_workspace_recipe |
Compares a recipe with live state and compiles chosen outcomes into typed changes |
get_operation |
The durable result of one operation or proposal owned by you |
import_skill |
Installs one exact public GitHub-hosted SKILL.md on an editable Agent |
manage_agent_skill |
Enables, disables, or removes one named installed skill |
propose_skill_import |
The older frozen review flow for a skill import |
propose_workspace_changes |
Creates the one read-only review for a consequential edit |
apply_workspace_changes |
Applies typed changes with durable idempotency and per-item outcomes |
confirm_workspace_change |
Applies the frozen operations behind one proposal |
undo_workspace_change |
Reverses one eligible operation at its exact resulting revision |
revoke_setup_link |
Revokes one unused setup link, and optionally issues a fresh one |
A change is active on the next newly admitted Slack event, including a reply in an existing thread. A response already in flight keeps the runtime plan it was admitted with.
Roles and scope
Chickpea roles decide what a client may do. Slack workspace roles do not. Every request re-resolves the live membership and access overlay, and tool arguments cannot select a user, organization, membership, Slack requester, or credential scope.
| Actor | Inspect workspace | Operational changes | Members |
|---|---|---|---|
| Owner | Yes | Yes | Yes |
| Admin | Yes | Yes | No |
| Member | Editable Agents only | Create and edit permitted Agents | No |
An external MCP client acts on the Agents you are permitted to edit, with no implied acting Agent. That is the difference from Slack, where a routed Agent may manage itself and @Chickpea may create Agents. Provider inspection and provider mutations stay Owner and Admin only, and their results expose availability and affected Agents, never a key or an environment secret. Deployment-provided credentials are visibly read-only.
Proposals and confirmation
The same gate that guards Slack guards MCP. Requests are scoped to your permissions and held to the same approvals.
- No ceremony for small edits. Simple reversible single-field changes apply directly, and you can undo them.
- Proposals before consequences. Two kinds of change arrive as a frozen read-only proposal: anything the Agent inferred rather than you stated, and anything that changes what an Agent can do, reach, or delete. Nothing applies until you approve it. That covers deleting an Agent, schedule, or durable memory entry, changing member authority, removing or replacing credentials, expanding capability scope, disabling an Agent that is published to a channel, archiving or restoring an Agent, granting or revoking channel reach, and overwriting an existing Agent from a recipe.
- The preview is the single approval boundary.
confirm_workspace_changeaccepts only the proposal handle and applies the frozen operations. It cannot reinterpret them. - The same requester confirms from the same client. Proposals do not expire, and a newer proposal from you at the same origin supersedes the older pending one. A changed target revision, digest, permission, requester, acting Agent, or origin makes the change set stale or denied before its first write, so inspect again and present a fresh diff.
- One base Agent is created immediately.
apply_workspace_changescreates a sufficiently understood base Agent when the request is exactly onecreate_agentoperation.propose_workspace_changesrejects Agent creation outright. Channel publication stays a separate, confirmation-gated step. - Batches cap at 25 ordered operations.
dependsOngives a progressive batch its prerequisites, and a failed prerequisite skips only its dependents. Such a batch is not globally atomic; every item returns its own durable disposition.
confirmation_required, setup_required, skipped, and failed are per-item dispositions, not transport failures. A partial result means an earlier item applied and a later one did not; it is not permission to replay the whole set.
Resources the server publishes
| URI | What it holds |
|---|---|
chickpea://guide/agent-authoring/v1 |
Canonical versioned guidance for exploring, creating, and editing Agents, with its packaged skill-creation.md procedure |
chickpea://schema/operations/v2 |
The stable tool and operation-kind inventory for this contract |
chickpea://workspace |
The same non-secret configuration inspect_workspace returns |
Read the authoring guide before turning a conversation into configuration. propose_workspace_changes and import_skill take the current guide version as an argument, and a proposal result repeats the guide version, URI, and digest, so you can prove which guidance produced the preview.
Credentials and setup links
MCP tools never accept a provider key, OAuth code, connector header, repository installation credential, Slack token, or secret-bearing URL. When access is missing, the client hands back a link instead. prepare_connector_setup returns an authenticated Admin handoff URL locked to one Agent, and a management operation can add request_setup for an exact connection, repository grant, or model provider. A human finishes it in the browser.
The setup page shows the connector, target, requested scopes, and replacement warning, and it cannot change those values. Validation clears the submitted fields, activates the connection once, and writes a non-secret receipt such as:
alex@northstar.example has been connected to Gmail connector.The receipt may name the target, scopes, initiator, operation ID, and a provider-returned account label. It never includes a token, code, key, client secret, header value, or repository installation credential. An MCP-origin receipt comes back through get_operation and is also sent to you in Slack.
Revoke access
- Disconnect in the client. Remove or revoke the MCP connection so the client stops holding a refresh token. The authorization server’s revocation endpoint is
/api/auth/oauth2/revoke. - Suspend or remove the member. In Admin, under Team, change the person’s status. This blocks live MCP requests immediately, without waiting for client cleanup. A demoted, suspended, removed, or mismatched person loses MCP authority even if a previously issued token has not reached its nominal expiry.
- Roll the surface back. An operator can disable the public management surface by removing its route at deployment or rolling back the artifact. Do not delete OAuth or management state while doing it: admitted work, durable operations, proposals, setup revocation, and receipts must stay explainable.
Next steps
- Admin: the browser door to the same controls, and who may sign in.
- How Chickpea works: the three doors and the one service behind them.
- Authority and confirmation: where authority comes from and why the confirmation boundary sits where it does.
- Management MCP tools: the tool-by-tool lookup for the management MCP.