---
title: "Connect a coding agent over MCP"
description: "Point an MCP client at your deployment's /mcp endpoint, authorize it with Slack, and manage your workspace from a coding agent."
---

> 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.

# Connect a coding agent over MCP

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/auth` return `404` until 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

1. **Add the server**

   In your client, add a remote or custom MCP server and give it your deployment URL ending in `/mcp`:

```text
https://<your-deployment>/mcp
```

   Do not create or paste a bearer token. Chickpea issues its own.
2. **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`.
3. **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.
4. **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:

- **`401` with 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_change` accepts 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_changes` creates a sufficiently understood base Agent when the request is exactly one `create_agent` operation. `propose_workspace_changes` rejects Agent creation outright. Channel publication stays a separate, confirmation-gated step.
- **Batches cap at 25 ordered operations.** `dependsOn` gives 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.

> **Caution**
>
> Anyone who can see a setup link can complete its exact frozen action without signing into Chickpea. Share it as a credential. The link expires after 24 hours, and `revoke_setup_link` cancels an unused one; reissuing invalidates the prior link.

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:

```text
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](/admin): the browser door to the same controls, and who may sign in.
- [How Chickpea works](/start/how-it-works): the three doors and the one service behind them.
- [Authority and confirmation](/security/authority-and-confirmation): where authority comes from and why the confirmation boundary sits where it does.
- [Management MCP tools](/reference/management-mcp-tools): the tool-by-tool lookup for the management MCP.

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