# info.summary
The management MCP server and OAuth 2.1 endpoints of a self-hosted Chickpea deployment.

# info.description
Chickpea is an open source Slack app that gives a workspace named AI teammates, deployed to your own Cloudflare account or a Node host.

Every deployment serves one machine door: a Model Context Protocol server at /mcp, protected by OAuth 2.1 with PKCE and a single scope, `chickpea:workspace`. A coding agent or any MCP client discovers the protected-resource metadata, registers itself as a public client, sends a person through Sign in with Slack, and then calls the 17 tools listed under the /mcp operation.

There is no API key, no password, and no per-request billing. Authority comes from the live Chickpea membership of the person who authorized the client, and consequential changes come back as a proposal that a person confirms.

The official command line, `chickpea-cli` on npm (https://github.com/pejmanjohn/chickpea/tree/main/packages/cli#readme), speaks this API from a shell: `npx chickpea-cli doctor https://<deployment>` checks the discovery documents, the JWKS, and the unauthenticated 401 challenge; `login` runs the public-client flow below; `call <tool>` invokes any tool under /mcp and prints its envelope. It never takes a token as an argument.

Versioning: the API is versioned by the MCP protocol version a client negotiates in the `MCP-Protocol-Version` header (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07) and by the contract version the server reports in its initialize response, currently 2.5.0; a breaking change to the tools or their arguments bumps the major. The OAuth endpoints follow their RFCs and carry no version of their own.

This document describes the API each deployment serves at its own origin. chickpea.co, where it is published, is the marketing site and answers these paths with a JSON problem that points here. Facts checked against the source on 2026-09-04.

# servers[].description
Your own Chickpea deployment. The hostname is the one Cloudflare or your Node host gave it; there is no shared instance.

# servers[].variables.deployment.description
The hostname of your Chickpea deployment. HTTPS is required; loopback is allowed for local development.

# tags[].description
The management MCP server, Streamable HTTP transport.

# tags[].description
Metadata a client reads before it authorizes, per RFC 9728 and RFC 8414.

# tags[].description
Registration, authorization, tokens, and revocation, per RFC 7591, RFC 6749, RFC 7636, and RFC 7009.

# paths./mcp.post.summary
Send a JSON-RPC message to the management MCP server

# paths./mcp.post.description
The Model Context Protocol endpoint, Streamable HTTP transport, stateless. Send one JSON-RPC 2.0 request or batch; the server identifies itself as `chickpea-workspace` 2.5.0. It accepts every method the protocol defines: initialize, tools/list, tools/call, resources/list, resources/read, and so on.

Tools (`tools/call` with `params.name`):

- `inspect_workspace` (read-only): Current non-secret Agents, skills, connections, repositories, channels, provider availability, and Owner-only team authority.

- `prepare_connector_setup` (read-only): A browser handoff URL for connecting one catalog service to one editable Agent.

- `discover_slack_channels` (read-only): Channels in the connected Slack workspace, before publishing an Agent.

- `test_mcp_connection` (read-only): Tests one saved Agent MCP connection and returns a sanitized result plus discovered tools.

- `inspect_memory` (read-only): The single memory body owned by one Agent.

- `inspect_routines` (read-only): Schedules and their safely projected content.

- `export_workspace_recipe` (read-only): Selected Agents and their connection requirements as a versioned, secret-free recipe.

- `preview_workspace_recipe` (read-only): Compares a recipe with live state and compiles chosen outcomes into typed changes.

- `get_operation` (read-only): The durable result of one operation or proposal owned by the caller.

- `import_skill` (applies a change): Installs one exact public GitHub-hosted SKILL.md on an editable Agent.

- `manage_agent_skill` (applies a change): Enables, disables, or removes one named installed skill.

- `propose_skill_import` (creates a proposal): The frozen review flow for a skill import.

- `propose_workspace_changes` (creates a proposal): Creates the one read-only review for a consequential edit.

- `apply_workspace_changes` (applies a change): Applies typed changes with durable idempotency and per-item outcomes.

- `confirm_workspace_change` (applies a change): Applies the frozen operations behind one proposal.

- `undo_workspace_change` (applies a change): Reverses one eligible operation at its exact resulting revision.

- `revoke_setup_link` (applies a change): Revokes one unused setup link, and optionally issues a fresh one.

Resources (`resources/read` with `params.uri`):

- `chickpea://guide/agent-authoring/v1`: Canonical versioned guidance for exploring, creating, and editing Agents.

- `chickpea://schema/operations/v2`: The stable tool and operation-kind inventory for this contract.

- `chickpea://workspace`: The same non-secret configuration inspect_workspace returns.

Every tool returns `{ "ok": true, "result": ... }` or `{ "ok": false, "error": { "code", "message" } }` with the MCP `isError` flag set. Tool arguments never carry a credential; when access is missing, the result carries a setup link a person finishes in the browser. Bodies over 1 MiB are refused with 413.

# paths./mcp.post.parameters[].description
The protocol version negotiated during initialize. Sent on every request after initialize, per the Streamable HTTP transport.

# paths./mcp.post.parameters[].description
application/json for a single JSON response, text/event-stream to allow a server-sent event stream. Clients normally send both.

# paths./mcp.post.responses.200.description
The JSON-RPC response, as JSON or as a server-sent event stream depending on the Accept header the client sent.

# paths./mcp.post.responses.200.content.text/event-stream.schema.description
One or more `data:` events, each a JSON-RPC response.

# paths./mcp.post.responses.400.description
The body was not a readable JSON-RPC message.

# paths./mcp.post.responses.401.description
No bearer token, or an invalid one. The WWW-Authenticate header carries the protected-resource metadata URL and the scope, so a client can start authorization.

# paths./mcp.post.responses.403.description
The token is valid but lacks `chickpea:workspace`, or the live Chickpea membership, role, or scope no longer permits the request.

# paths./mcp.post.responses.404.description
The deployment has not finished setup: Slack is not connected or the deployment is not healthy, so the management surface is not mounted yet.

# paths./mcp.post.responses.503.description
MCP is temporarily unavailable. Retry later.

# paths./.well-known/oauth-protected-resource.get.summary
Protected-resource metadata for the origin (RFC 9728)

# paths./.well-known/oauth-protected-resource.get.description
Names the /mcp resource, the authorization server at /api/auth, and the one supported scope. Returns 404 until the deployment has connected Slack.

# paths./.well-known/oauth-protected-resource/mcp.get.summary
Protected-resource metadata for /mcp (RFC 9728)

# paths./.well-known/oauth-protected-resource/mcp.get.description
The same document as the origin-level one, at the path a client derives from the /mcp resource URL. Clients read this first.

# paths./.well-known/oauth-authorization-server/api/auth.get.description
The issuer is the deployment origin plus /api/auth. The document names the authorization, token, registration, and revocation endpoints, `S256` as the only PKCE method, and `chickpea:workspace` as the only scope. The same document is at /api/auth/.well-known/oauth-authorization-server.

# paths./api/auth/jwks.get.summary
The JSON Web Key Set that signs access tokens

# paths./api/auth/jwks.get.description
Access tokens are EdDSA JWTs whose issuer is the deployment origin plus /api/auth and whose audience is the /mcp resource, valid for at most 20 minutes.

# paths./api/auth/oauth2/register.post.description
Dynamic registration for public clients only: `token_endpoint_auth_method` must be `none`, the application type `native` or `web`, grants `authorization_code` with an optional `refresh_token`, response type `code`, 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 per deployment.

# paths./api/auth/oauth2/register.post.responses.201.description
The registered client. There is no client secret.

# paths./api/auth/oauth2/register.post.responses.400.description
The metadata broke one of the rules above.

# paths./api/auth/oauth2/register.post.responses.429.description
Too many registrations in the window, or too many clients on this deployment.

# paths./api/auth/oauth2/register.post.responses.429.headers.Retry-After.description
Seconds until a registration will be accepted again.

# paths./api/auth/oauth2/register.post.responses.503.description
Authentication is not available on this deployment yet.

# paths./api/auth/oauth2/authorize.get.summary
Start the authorization code flow with PKCE

# paths./api/auth/oauth2/authorize.get.description
Opened in a browser. Chickpea stores a one-use continuation, sends the person to Sign in with Slack, then shows "Allow workspace management?" naming the client and the scope. On Allow, the browser is redirected to the registered redirect URI with the code.

# paths./api/auth/oauth2/authorize.get.parameters[].description
One of the registered redirect URIs, exactly.

# paths./api/auth/oauth2/authorize.get.parameters[].description
Defaults to `chickpea:workspace`, the only scope.

# paths./api/auth/oauth2/authorize.get.responses.302.description
Redirect into Sign in with Slack, and eventually back to the redirect URI with `code` and `state`.

# paths./api/auth/oauth2/authorize.get.responses.400.description
A malformed or unsigned browser request.

# paths./api/auth/oauth2/token.post.summary
Exchange a code or refresh token for an access token

# paths./api/auth/oauth2/token.post.description
Public client, so no client authentication: the PKCE verifier proves possession. Access tokens are short-lived (20 minutes) and bound to the /mcp resource.

# paths./api/auth/oauth2/token.post.responses.200.description
A token response per RFC 6749 section 5.1.

# paths./api/auth/oauth2/token.post.responses.503.description
Authentication is not available on this deployment yet.

# paths./api/auth/oauth2/revoke.post.summary
Revoke a refresh or access token (RFC 7009)

# paths./api/auth/oauth2/revoke.post.description
Disconnecting the client in its own UI usually calls this. Suspending or removing the member in Admin blocks live requests immediately, without waiting for revocation.

# paths./api/auth/oauth2/revoke.post.responses.200.description
The token is revoked, or was already invalid.

# components.securitySchemes.oauth2.description
OAuth 2.1 with PKCE (S256), public clients registered dynamically, and one scope. The person who authorizes signs in with Slack; their live Chickpea role decides what each call may do. Metadata: /.well-known/oauth-authorization-server/api/auth on the deployment.

# components.securitySchemes.oauth2.flows.authorizationCode.scopes.chickpea:workspace
Inspect and change the Chickpea workspace the signed-in member may edit: Agents, skills, connections, repositories, schedules, memory, and setup links. Every call is re-checked against the member's live role, and consequential changes come back as a proposal that a person confirms.

# components.schemas.JsonRpcRequest.description
A JSON-RPC 2.0 request or notification, as the Model Context Protocol defines it.

# components.schemas.JsonRpcRequest.properties.method.description
An MCP method, for example initialize, tools/list, tools/call, resources/list, resources/read.

# components.schemas.JsonRpcRequest.properties.params.description
For tools/call: `name` (one of the tool names above) and `arguments`.

# components.schemas.ClientRegistrationRequest.properties.redirect_uris.description
Exact HTTPS URLs, or http loopback URLs. No wildcards.

# components.schemas.TokenRequest.properties.code_verifier.description
The PKCE verifier for the challenge sent to /authorize.

# components.schemas.TokenResponse.properties.access_token.description
An EdDSA JWT bound to the /mcp resource, valid for at most 20 minutes.