MCP Reference

The Envelope MCP server exposes sixteen tools covering execution, observability, team building, and model routing — accessible from Claude.ai, ChatGPT, and Claude Code.

Server URL: https://mcp.openenvelope.org/api/mcp

Connect

Claude.ai and ChatGPT

Claude.ai and ChatGPT connect via OAuth 2.0 — no API key needed.

1. Paste https://mcp.openenvelope.org/api/mcp into your AI tool's connector settings
2. Complete the OAuth sign-in with your Envelope account
3. Approve access — your workspace appears as tools in the conversation

→ Connect to Claude.ai step-by-step
→ Connect to ChatGPT step-by-step

Claude Code

Add the Envelope skill to your Claude Code installation. The skill provides the MCP server URL and configures authentication using your personal API key.

→ Claude Code install guide

Authentication

OAuth tokens — Claude.ai and ChatGPT use OAuth access tokens issued during the sign-in flow. No manual setup required.

API keys — Claude Code and direct API access use a personal API key from your account settings:

Authorization: Bearer $ENVELOPE_KEY

API keys are scoped to an org. All read and write operations act on installs and runs owned by that org.

Rate limits

• 200 requests per minute per API key
• Run endpoints (POST /api/installs/:id/run) are additionally limited to 10 concurrent runs per org
• 429 responses include a Retry-After header

Errors

All errors return JSON with a message field and an HTTP status code:

List Installs

Returns all installs associated with your API key's org. Use this to discover available install IDs before calling run or gate endpoints.

GET /api/installs
Authorization: Bearer $ENVELOPE_KEY

Response

{
  "installs": [
    {
      "id": "{your-install-id}",
      "templateId": "tmpl_xyz",
      "templateName": "Outbound Sales Team",
      "templateSlug": "sales-team-v1",
      "templateVersion": 3,
      "platform": "paperclip",
      "status": "completed",
      "createdAt": "2026-04-01T12:00:00.000Z"
    }
  ]
}

Run a Team

Triggers a run on an installed team. The connection stays open until the team finishes or a gate is reached.

POST /api/installs/:id/run
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "task": "Research the top 5 competitors for Acme Corp and summarise their pricing"
}

Response — completed

{
  "runId": "{your-run-id}",
  "status": "completed",
  "output": "...",
  "tokenUsage": { "input": 1200, "output": 340 }
}

Response — gate reached

{
  "runId": "{your-run-id}",
  "status": "gate",
  "gate": {
    "id": "gate_xyz",
    "agentId": "supervisor",
    "message": "Ready to send outbound email to 12 contacts. Approve?",
    "context": { ... }
  }
}

When status is gate, the run is paused. Use Continue after Gate or Reject a Gate to proceed.

Webhook Trigger

Triggers a run via a signed webhook URL — no API key needed in the request. Useful for external system integrations.

POST /api/installs/:id/webhook/:token
Content-Type: application/json

{
  "task": "New Zendesk ticket #4821 — billing issue from enterprise customer"
}

The webhook token is generated when the install is created. Treat it as a secret.

Continue after Gate

Resumes a paused run after a human approves the gate.

POST /api/installs/:id/continue
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "runId": "{your-run-id}",
  "gateId": "gate_xyz",
  "feedback": "Approved — send to the first 5 only"
}

The feedback field is optional. If provided, it is passed back to the agent as context before the run resumes.

Reject a Gate

Stops a paused run without resuming it. The run status is set to cancelled.

POST /api/installs/:id/reject-gate
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "runId": "{your-run-id}",
  "gateId": "gate_xyz",
  "reason": "Too many contacts — needs more filtering first"
}

Cancel a Run

Cancels an in-progress run. Has no effect on already-completed or already-cancelled runs.

POST /api/installs/:id/cancel-run
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "runId": "{your-run-id}"
}

List Runs

Returns runs for one or more installs. Requires either installId or templateId as a query parameter.

GET /api/runs?installId={your-install-id}
Authorization: Bearer $ENVELOPE_KEY

Query parameters

Resolve Identity

Returns the install identity associated with the current API key. Useful for confirming which install an API key is scoped to.

GET /api/installs/whoami
Authorization: Bearer $ENVELOPE_KEY

Response

{
  "installId": "{your-install-id}",
  "orgId": "org_xyz",
  "platform": "paperclip"
}

Browse Templates

Returns published templates available to install. No authentication required.

GET /api/templates

Response

{
  "templates": [
    {
      "id": "tmpl_xyz",
      "name": "Outbound Sales Team",
      "slug": "sales-team-v1",
      "description": "...",
      "version": 3,
      "platform": "paperclip"
    }
  ]
}

Team Schema

Returns the JSON Schema for the team definition format. Use this to validate .envelope.json files before uploading.

GET /api/schema

Returns the full JSON Schema object for the current schema version.

Generate Team

Generate a team definition from a natural-language description. Returns a proposed JSON definition for review — the team is not saved or installed yet. Confirm with the user, then call Create Team to save it.

POST /api/templates/generate
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "description": "Monitor GitHub issues and draft response suggestions",
  "name": "GitHub Issue Responder"
}

Response

{
  "definition": {
    "name": "GitHub Issue Responder",
    "agents": [
      { "key": "monitor", "role": "fetch new GitHub issues" },
      { "key": "drafter", "role": "draft response suggestions" }
    ],
    "requiredSecrets": ["GITHUB_TOKEN"]
  }
}

Create Team

Save a team definition to the workspace as a private draft. Returns a template ID for use with Install Team.

POST /api/templates
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "name": "GitHub Issue Responder",
  "description": "Monitors issues and drafts reply suggestions.",
  "definition": { ... }
}

Response

{
  "id": "tmpl_abc123",
  "slug": "github-issue-responder",
  "name": "GitHub Issue Responder",
  "status": "draft"
}

Update Team

Modify an existing team definition using a natural-language instruction — add or change agents, update roles, or adjust configuration without replacing the whole definition.

POST /api/templates/:id/apply
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{
  "instruction": "Add a summariser agent that writes a short CRM note after each issue"
}

Install Team

Install a template into the workspace so it can be triggered. If all required credentials are in the org vault, installation completes immediately. If credentials are missing, the response includes a setupUrl — secrets must never pass through the API or a conversation.

POST /api/installs
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{ "templateId": "tmpl_abc123" }

Response — vault covered all credentials

{ "installId": "{your-install-id}", "status": "completed" }

Response — credentials needed

{
  "installId": "{your-install-id}",
  "status": "pending_credentials",
  "setupUrl": "https://openenvelope.org/workspace/installs/{your-install-id}"
}

Uninstall Team

Remove an installed team. Cancels any active runs.

DELETE /api/installs/:installId
Authorization: Bearer $ENVELOPE_KEY

Publish Team

Publish a draft or private template to the public marketplace.

POST /api/templates/:id/publish
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{ "changeLog": "Initial release." }

List Agent Models

Returns every agent in an install with its current model assignment. effectiveModel reflects the full resolution order: deployer override → definition model → auto-routing.

GET /api/installs/:installId/agents
Authorization: Bearer $ENVELOPE_KEY

Response

{
  "installId": "{your-install-id}",
  "agents": [
    {
      "agentKey": "triage",
      "name": "Triage Agent",
      "definitionModel": null,
      "overrideModel": "openai:gpt-5-mini",
      "effectiveModel": "openai:gpt-5-mini"
    }
  ]
}

Set Agent Model

Pin a specific model to an agent within an install. Takes effect on the next run. Pass "auto" to reset without calling the delete endpoint.

PATCH /api/installs/:installId/agents/:agentKey/model
Authorization: Bearer $ENVELOPE_KEY
Content-Type: application/json

{ "model": "openai:gpt-5-mini" }

Valid models: openai:gpt-5.4, openai:gpt-5-mini, openai:gpt-5-nano, openai:o4-mini, openai:o3, anthropic:claude-opus-4-5, anthropic:claude-sonnet-4-5, anthropic:claude-haiku-4-5

Response

{
  "ok": true,
  "installId": "{your-install-id}",
  "agentKey": "triage",
  "model": "openai:gpt-5-mini",
  "routing": "override"
}

Reset Agent Model

Clear a model override for an agent, returning it to automatic routing.

DELETE /api/installs/:installId/agents/:agentKey/model
Authorization: Bearer $ENVELOPE_KEY

Response

{
  "ok": true,
  "installId": "{your-install-id}",
  "agentKey": "triage",
  "routing": "auto"
}

Frequently asked questions

Is the MCP server free to use? Access to the MCP server requires an Envelope account. The Free plan includes MCP access with sign-in required. Pro and Team plans include higher rate limits and priority queue access. See pricing for details.

Do I need a separate API key for the MCP server? For Claude Code and direct API access, use your Envelope API key as the Bearer token — generate one from Account → API Keys. For Claude.ai and ChatGPT, OAuth handles authentication automatically through the connector flow.

Can I run multi-agent teams through the MCP server without writing any code? Yes. Connect the MCP server to Claude.ai or ChatGPT and you can design, install, and run multi-agent workflows entirely through conversation — no code, no infrastructure. See the MCP host setup guide for step-by-step instructions.

What's the difference between the MCP server and the REST API? The MCP server is designed for AI tools — Claude, ChatGPT, Claude Code. It exposes high-level operations like run team, continue gate, and browse templates. The REST API is for programmatic integration — CI/CD pipelines, custom dashboards, and server-side automation workflows.

→ Design a multi-agent AI team without writing code — how to use Envelope to design and run AI workflows entirely without engineering