Management MCP tools

The management MCP server is the OAuth-protected Model Context Protocol endpoint a deployment publishes at /mcp, so a coding agent can read and change Chickpea configuration. Where Admin is the browser door onto that configuration and the @Chickpea Agent is the Slack door, the management MCP is the machine door onto the same workspace management service. This page lists the 17 tools, the 3 resources, the endpoints, and the confirmation posture of every operation kind.

The source of truth is src/management/mcp.ts, which registers the tools and resources; src/management/schemas.ts, which defines the accepted arguments; and src/management/policy.ts, which decides which operations need confirmation. Tool names and operation kinds are code identifiers and are written exactly as the code spells them, including routine where the product word is schedule.

Endpoints and metadata

The server identifies itself as chickpea-workspace version 2.5.0. The single product scope is chickpea:workspace.

Requests carry a bearer token. The token is verified as an EdDSA JWT whose issuer is the deployment origin plus /api/auth and whose audience is the /mcp resource, with a maximum age of 20 minutes and 30 seconds of clock tolerance. A request without a token returns 401 with a protected-resource challenge; an invalid token returns 401 with invalid_token; a token missing chickpea:workspace returns 403 with insufficient_scope. Every request then re-resolves the live Chickpea membership, and a member who is suspended or removed is refused.

Every tool returns the same envelope: { "ok": true, "result": ... } on success, or { "ok": false, "error": { "code": ..., "message": ... } } on failure. The failing envelope also sets the MCP isError flag.

Tool summary

An Agent is editable by an Owner or an Admin, by the member whose membership created it, or by any member when its editPolicy is all_workspace_members.

inspect_workspace

Effect read-only. Authority any live member. Arguments none.

Returns the non-secret snapshot the other tools work from: the organization id, the connector catalog, and every editable Agent with its revision, instructions, enabled flag, lifecycle, edit policy, Slack presence, model, skills, connections, and repositories. A Member sees only editable Agents; an Owner also sees team authority. Revisions from this snapshot are the values other operations pass as expectedRevision.

prepare_connector_setup

Effect read-only, and writes no Agent configuration. Authority a member who may edit the target Agent. Arguments agentId (required on the MCP surface), connector, ownerKind (team or member).

Turns one connector catalog id or display name, for example gmail or Gmail, into a browser handoff URL locked to that Agent. The result carries the Agent, the connector, the owner kind, and handoffUrl. From an MCP client the handoff URL points into Admin at /admin/agents/<agentId>/connections/new/<connectorId>/<ownerKind> and carries no setupOperationId; the pre-authorized setup-link forms are issued on the trusted Slack route. An unknown connector fails with invalid_request and a list of catalog names. The resulting connection belongs to that Agent alone.

discover_slack_channels

Effect read-only. Authority any live member. Arguments refresh (optional boolean, default false).

Lists channels in the connected Slack workspace so a channel id can be chosen before publishing an Agent. It fails with invalid_request when channel discovery is unavailable on the deployment.

test_mcp_connection

Effect read-only. Authority a member who may edit the target Agent. Arguments agentId, connectionId.

Calls one saved MCP connection with its stored write-only credential and returns a sanitized result plus the tools discovered on that server. The credential is never returned and never appears in the arguments.

inspect_memory

Effect read-only. Authority a member who may edit the target Agent. Arguments agentId.

Returns the one durable memory body owned by that Agent, as agentId, body, and revision. The revision is the value update_agent_memory passes as expectedRevision.

inspect_routines

Effect read-only. Authority any live member with access to the workspace. Arguments workspaceId, optional channelId, optional routineId.

Returns saved schedules with their id, state, version, name, description, task text, trigger kind, schedule expression, timezone, output policy, next run time, owning Agent, and a contentAccess value of public, private, or authorization_unknown. Content is filtered by the edit policy of the owning Agent. In a one-to-one DM the server derives the private conversation from the trusted Slack origin, so channelId is omitted there.

export_workspace_recipe

Effect read-only. Authority any live member. Arguments agentIds (optional, at most 100).

Returns a schema-versioned, secret-free recipe holding instructions, model choice, inline skills, connection requirements, and exact repository names for the selected editable Agents. It excludes workspace and channel ids, members, Slack and provider account identifiers, credentials, repository installation ids, Agent memory, and channel grants.

preview_workspace_recipe

Effect read-only. Authority any live member. Arguments recipe, optional agentStrategy (clone, update, or skip).

Compares a recipe with live state and compiles the chosen outcomes into ordinary typed operations for apply_workspace_changes. Name conflicts return clone, update, and skip; duplicate matches return ambiguous. Missing connectors, repositories, and provider credentials become setup-required operations. Unsupported versions, malformed requirements, duplicate symbols, unsafe URLs, unsupported model providers, and batches over 25 operations fail before any write.

propose_skill_import

Effect proposes; installs nothing. Authority a member who may edit the target Agent. Arguments agentId, source (at most 2,000 characters), optional skillName, idempotencyKey, guideVersion.

Resolves one public GitHub-hosted SKILL.md inside the management service and creates the ordinary requester-bound review for adding or replacing it. A source holding several skills returns selection_required with bounded candidate names, descriptions, paths, and immutable source URLs, and changes nothing. Otherwise the result is a proposal: proposalId, digest, guide metadata, presentation.slack, and confirmationTool. This is the review path deliberate MCP clients use.

import_skill

Effect applies immediately. Authority a member who may edit the target Agent, on the trusted Slack route. Arguments the propose_skill_import arguments plus optional replaceExisting.

Pins the inspected commit and installs one bounded scriptless skill without a proposal, returning status: "installed" with operationId, activation: "next_turn", undoAvailable, and a Slack-ready receipt. Identical content returns already_installed. Different content under the same name returns replacement_confirmation_required with the exact clarification text required before a retry with replaceExisting: true. Packaged scripts are rejected, because Chickpea inline skills cannot execute imported files.

Immediate import requires the exact source in the authenticated current requester message, so a call from an MCP client fails with invalid_request and the message Immediate skill import requires the exact GitHub source in the current requester message. No change was made. MCP clients use propose_skill_import instead.

manage_agent_skill

Effect applies immediately. Authority a member who may edit the target Agent. Arguments agentId, action (enable, disable, or remove), skillName, idempotencyKey.

Changes one named installed skill, preserves every other skill, and returns status of updated or unchanged with action, skillName, operationId, activation, undoAvailable, and a Slack-ready receipt. An authenticated MCP invocation is already the exact typed command, so no proposal is created. On the Slack route the current message must explicitly name that action and skill, or the call fails with invalid_request. propose_workspace_changes refuses an exact qualifying single-skill command and points back to this tool.

propose_workspace_changes

Effect proposes; writes no configuration. Authority depends on the operations in the batch. Arguments idempotencyKey (at most 256 characters), guideVersion, authoringReason, operations (1 to 25).

Creates the one read-only, requester-bound review for a consequential edit. guideVersion must equal the current Agent-authoring guide version, 1.0.28, or the call fails with a message naming chickpea://guide/agent-authoring/v1. authoringReason is one of agent_creation, agent_edit, skill_creation, skill_edit, or onboarding. Agent creation is rejected here, and so is request_setup. The result carries proposalId, status: "pending", digest, guide version and digest, a preview of changes and missing setup, presentation.slack, and confirmationTool: "confirm_workspace_change". Retrying the same bound key with the same operation digest returns the original proposal; reusing the key for different content fails closed.

apply_workspace_changes

Effect applies, and returns a proposal for anything whose posture is confirmation. Authority depends on the operations in the batch. Arguments idempotencyKey, operations (1 to 25).

Applies typed changes with durable idempotency and one disposition per item. Each operation carries an itemId and may carry dependsOn with up to 25 prerequisite item ids; a failed prerequisite skips only its dependents. The batch is not globally atomic.

A create_agent operation is applied immediately rather than proposed, unless its editPolicy is all_workspace_members. It must be the only operation in the request, and its mcpServers, apiConnections, and repositories arrays must be empty; either violation fails with base_agent_capabilities_require_setup. The skill name agent-authoring is reserved and is rejected in any create or update.

The result is operationId, idempotencyKey, status of completed, partial, or confirmation_required, effectiveRevision, activation: "next_turn", and outcomes. Each outcome names its itemId, its operationKind, and a disposition of applied, confirmation_required, setup_required, chickpea_handoff, failed, or skipped, plus proposalId, setupOperationId, setupUrl, handoffUrl, undoAvailable, code, or warning where they apply. A partial status means an earlier item applied and a later one failed; it is not permission to replay the batch.

confirm_workspace_change

Effect applies the frozen operations. Authority the same live requester, from the same MCP client or Slack thread. Arguments proposalId.

Applies a pending proposal exactly as previewed and cannot reinterpret it. The result is the same apply result shape, reporting applied, setup_required, stale, denied, failed, or partial. Proposals do not expire, and a newer proposal from the same requester and 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.

undo_workspace_change

Effect applies the inverse, or returns a proposal when the inverse has become consequential. Authority the requester who owns the operation. Arguments operationId, idempotencyKey.

Reverses one eligible mutation at its exact resulting revision, and fails with undo_unavailable when no undo is recorded, when the recorded revision has moved on, or when the operation belongs to another requester. A trusted connector call immediately reverses an exact manage_agent_skill receipt. Other inverses run through the same consequence-based policy as any other operation, so a risky inverse comes back as a proposal.

get_operation

Effect read-only. Authority the requester, membership, organization, and origin that created the record. Arguments operationId.

Returns the durable record for one apply request, proposal, change-set proposal, or setup link, or { "operation": null } when nothing matches. A record owned by anyone else returns operation_not_found rather than a permission error. Setup URLs are issued once and are not stored in pollable results, so polling reveals lifecycle and non-secret receipts only.

revoke_setup_link

Effect applies; revokes a capability. Authority the requester who owns the setup link. Arguments setupOperationId, optional reissue (default false).

Revokes one unused setup link and, when reissue is true, issues a replacement. Setup links live for 24 hours from issue. The result carries the revoked status and, on reissue, a replacement setupOperationId and setupUrl. Reissue invalidates the prior link.

Operation kinds and confirmation postures

propose_workspace_changes and apply_workspace_changes carry typed operations. src/management/policy.ts classifies each one as immediate or confirmation before any write.

An update_agent operation needs confirmation for any of these reasons:

• recipe_overwrite. The operation sets that confirmationReason, which preview_workspace_recipe produces for an update.
• Disabling a published Agent. The Agent is currently enabled, the patch sets enabled: false, and the Agent holds at least one channel grant.
• Capability scope expansion. The patch widens what the Agent may reach.
• A capability or authority field. The patch touches apiConnections, mcpServers, repositories, or editPolicy.
• A compound change. The patch carries more than one field.
• A skill change. A skills-only patch needs confirmation unless the service proves both an exact requester command and a reversible local change.

The policy also names slackPresence among the capability fields, which the MCP patch schema does not accept.

Two decisions deny the call outright rather than proposing it: an operation that requires Admin authority from a Member returns operational_access_required, and update_member from a non-Owner returns owner_required.

Applied changes take effect on the next newly admitted Slack event, including a reply in an existing thread. A response already in flight keeps its frozen runtime plan.

Resources

The guide resource is the one a client reads before translating conversational intent into configuration. Its version, currently 1.0.28, is the value propose_workspace_changes and the skill import tools require in guideVersion, and a proposal repeats the version, URI, and digest so a client can prove which guidance produced the preview.

Argument limits