---
title: "Management MCP tools"
description: "Every tool, resource, and endpoint the Chickpea management MCP server exposes, with its authority and its confirmation posture."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.chickpea.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/admin/tour) 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

| Path | Purpose |
|---|---|
| `/mcp` | The MCP endpoint itself. It accepts every JSON-RPC method for the server. |
| `/.well-known/oauth-protected-resource/mcp` | Protected-resource metadata naming the `/mcp` resource and the `/api/auth` authorization server. |
| `/.well-known/oauth-protected-resource` | Protected-resource metadata at the origin root. |
| `/.well-known/oauth-authorization-server/api/auth` | Authorization-server metadata. |
| `/api/auth/.well-known/oauth-authorization-server` | The same metadata under the auth base path. |
| `/auth/mcp/login`, `/auth/mcp/consent` | The browser sign-in and consent pages a client opens during authorization. |

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

| Tool | Effect | Authority |
|---|---|---|
| `inspect_workspace` | Read-only | Any live member; team authority for an Owner only |
| `prepare_connector_setup` | Read-only, returns a handoff URL | A member who may edit the target Agent |
| `discover_slack_channels` | Read-only | Any live member |
| `test_mcp_connection` | Read-only | A member who may edit the target Agent |
| `inspect_memory` | Read-only | A member who may edit the target Agent |
| `inspect_routines` | Read-only | Any live member with access to the workspace |
| `export_workspace_recipe` | Read-only | Any live member; exports editable Agents only |
| `preview_workspace_recipe` | Read-only | Any live member |
| `propose_skill_import` | Proposes | A member who may edit the target Agent |
| `import_skill` | Applies | A member who may edit the target Agent, on the Slack route only |
| `manage_agent_skill` | Applies | A member who may edit the target Agent |
| `propose_workspace_changes` | Proposes | Depends on the operations in the batch |
| `apply_workspace_changes` | Applies or proposes | Depends on the operations in the batch |
| `confirm_workspace_change` | Applies | The same requester, from the same client |
| `undo_workspace_change` | Applies or proposes | The requester who owns the operation |
| `get_operation` | Read-only | The requester who owns the operation |
| `revoke_setup_link` | Applies | The requester who owns the setup link |

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.

| Operation kind | Posture | Condition |
|---|---|---|
| `create_agent` | Immediate | Confirmation when `editPolicy` is `all_workspace_members` |
| `update_agent` | Confirmation | Immediate only for one explicit reversible skill change |
| `delete_agent` | Confirmation | Always |
| `archive_agent` | Confirmation | Always |
| `restore_agent` | Confirmation | Always |
| `put_channel` | Immediate | Confirmation when an active channel becomes `archived`, which also needs Admin or Owner |
| `grant_agent_channel` | Confirmation | Immediate for the Slack channel the Agent was created in |
| `revoke_agent_channel` | Confirmation | Always |
| `update_member` | Confirmation | Owner only; any other role is denied with `owner_required` |
| `remove_provider_credential` | Confirmation | Admin or Owner; deployment-provided credentials are read-only |
| `update_agent_memory` | Immediate | Needs an editable Agent and the current memory revision |
| `save_routine` | Immediate | |
| `control_routine` | Immediate | |
| `run_routine` | Immediate | |
| `delete_routine` | Confirmation | Always |
| `reassign_routine_agent` | Confirmation | Always |
| `request_setup` | Immediate | Confirmation when the setup replaces an existing credential; provider credentials need Admin or Owner |

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

| URI | Contents |
|---|---|
| `chickpea://workspace` | The current `inspect_workspace` snapshot as JSON. |
| `chickpea://schema/operations/v2` | The operation inventory: `schemaVersion`, the 17 tool names, the 17 operation kinds, `activation: "next_turn"`, and the confirmation note. |
| `chickpea://guide/agent-authoring/v1` | The versioned Agent-authoring guide, its digest, and the packaged `skill-creation.md` procedure. |

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

| Limit | Value | Scope |
|---|---|---|
| Operations per call | 1 to 25 | `propose_workspace_changes`, `apply_workspace_changes` |
| `dependsOn` prerequisites | 25 | Each operation |
| `idempotencyKey` | 1 to 256 characters | Every mutating tool |
| Agent instructions | 100,000 characters | `create_agent`, `update_agent` |
| Skills per Agent | 100 | `create_agent`, `update_agent` |
| MCP connections per Agent | 50 | `create_agent`, `update_agent` |
| API connections per Agent | 50 | `create_agent`, `update_agent` |
| Repositories per Agent | 100 | `create_agent`, `update_agent` |
| Memory body | 65,536 characters | `update_agent_memory` |
| Schedule task text | 20,000 characters | `save_routine` |
| Skill import source | 2,000 characters | `propose_skill_import`, `import_skill` |
| Agent ids in a recipe export | 100 | `export_workspace_recipe` |

Source: https://docs.chickpea.co/reference/management-mcp-tools/index.mdx