Envelope
‹Docs
MCP
v1 · Live

MCP Reference

Generate and manage AI agent specs from Claude.ai, ChatGPT, or Claude Code. Server URL: https://mcp.openenvelope.org/api/mcp

Connect Claude.ai ·Connect ChatGPT ·Claude Code skill ·Agent skill document

Authentication

Pass your API key in the Authorization header on every request.

Authorization: Bearer env_live_xxxxxxxxxxxxxx

Personal keys

Tied to your account. Generated from Account → API Keys.

Org keys

Tied to a workspace, not an individual. Use these for CI/CD and shared automation. Generated from Org → API Keys.

Copy your key for use in examples below

Then: export ENVELOPE_KEY=<paste here>

Errors

Standard HTTP status codes. All error responses return a JSON body with a single error field.

2xx
Success

Request succeeded.

4xx
Client error

Bad request, missing auth, or resource not found.

5xx
Server error

Something went wrong on our end.

{ "error": "Install not found" }

Rate Limits

Requests exceeding the limit receive 429 Too Many Requests. The Retry-After header indicates how long to wait.

ScopeLimitWindow
All endpoints300 requests15 minutes
Auth routes20 requests15 minutes
GET

List Installs

Returns all installs associated with your API key's org. Use this to discover available install IDs and see the current state of your workspace.

GET
/api/installs
API Key Required
curl https://openenvelope.org/api/installs \
  -H "Authorization: Bearer $ENVELOPE_KEY"

Response

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

Resolve Identity

Returns the org and user associated with an API key. Useful for MCP servers or integrations confirming which workspace they're operating in.

GET
/api/auth/key-identity
API Key Required
curl https://openenvelope.org/api/auth/key-identity \
  -H "Authorization: Bearer $ENVELOPE_KEY"

Response

{
  "orgSlug": "acme",
  "orgId":   "org_abc",
  "userId":  "usr_xyz",
  "label":   "production"
}
GET

Browse Templates

Browse published team templates. No authentication required — these are publicly listed designs available to use or adapt as a starting point.

GET
/api/templates
No Auth
curl https://openenvelope.org/api/templates
GET
/api/templates/:id
No Auth
curl https://openenvelope.org/api/templates/01925000-0000-7000-8000-000000000001
GET

Team Schema

The canonical JSON schema for the Envelope team definition format. Use this to validate a team.json before publishing or importing.

GET
/schema/team/v1.json
No Auth
curl https://schema.openenvelope.org/team/v1.json
The schema is also published at https://schema.openenvelope.org/team/v1.json for use as a $schema reference in your team files.
POST

Generate Team

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

POST
/api/templates/generate
API Key Required
curl -X POST https://openenvelope.org/api/templates/generate \
  -H "Authorization: Bearer $ENVELOPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"]
  }
}
POST

Create Team

Save a team definition to the workspace as a private draft. Returns a template ID that can be used with Install Team.

POST
/api/templates
API Key Required
curl -X POST https://openenvelope.org/api/templates \
  -H "Authorization: Bearer $ENVELOPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Issue Responder",
    "description": "Monitors issues and drafts reply suggestions.",
    "definition": { "agents": [ ... ] }
  }'

Response

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

Update Team

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

POST
/api/templates/:id/apply
API Key Required
curl -X POST https://openenvelope.org/api/templates/tmpl_abc123/apply \
  -H "Authorization: Bearer $ENVELOPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Add a summariser agent that writes a short CRM note after each issue"
  }'
POST

Install Team

Install a template into the workspace, making it live and ready for your team. If all required credentials are already in the org vault, installation completes immediately. If credentials are missing, the response includes a setup link — secrets must never pass through the API or a chat conversation.

POST
/api/installs
API Key Required
curl -X POST https://openenvelope.org/api/installs \
  -H "Authorization: Bearer $ENVELOPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "tmpl_abc123" }'

Response — vault covered all credentials

{
  "installId": "inst_abc123",
  "status": "completed"
}

Response — credentials needed

{
  "installId": "inst_abc123",
  "status": "pending_credentials",
  "setupUrl": "https://openenvelope.org/workspace/installs/inst_abc123"
}
DELETE

Uninstall Team

Remove an installed team from your workspace and tear down any platform-side resources where applicable.

DELETE
/api/installs/:installId
API Key Required
curl -X DELETE https://openenvelope.org/api/installs/inst_abc123 \
  -H "Authorization: Bearer $ENVELOPE_KEY"
POST

Publish Team

Publish a draft or private team template to the public marketplace. The team must be saved first via Create Team.

POST
/api/templates/:id/publish
API Key Required
curl -X POST https://openenvelope.org/api/templates/tmpl_abc123/publish \
  -H "Authorization: Bearer $ENVELOPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "changeLog": "Initial release." }'
GET

List Agent Models

Returns every agent in an install with its current model assignment. effectiveModel is what will actually run — it reflects the full resolution order: deployer override → definition model → auto-routing.

GET
/api/installs/:installId/agents
API Key Required
curl https://openenvelope.org/api/installs/inst_abc123/agents \
  -H "Authorization: Bearer $ENVELOPE_KEY"

Response

{
  "installId": "inst_abc123",
  "agents": [
    {
      "agentKey": "triage",
      "name": "Triage Agent",
      "role": "classify incoming support tickets",
      "definitionModel": null,
      "overrideModel": "openai:gpt-5-mini",
      "effectiveModel": "openai:gpt-5-mini"
    },
    {
      "agentKey": "responder",
      "name": "Response Drafter",
      "role": "draft replies to customer messages",
      "definitionModel": "anthropic:claude-sonnet-4-5",
      "overrideModel": null,
      "effectiveModel": "anthropic:claude-sonnet-4-5"
    }
  ]
}
PATCH

Set Agent Model

Pin a specific model to an agent within an install. Applies to the install's current configuration. Pass "auto" to reset back to automatic routing without needing to call the delete endpoint.

PATCH
/api/installs/:installId/agents/:agentKey/model
API Key Required
curl -X PATCH https://openenvelope.org/api/installs/inst_abc123/agents/triage/model \
  -H "Authorization: Bearer $ENVELOPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "openai:gpt-5-mini" }'

Valid models

openai:gpt-5.4openai:gpt-5-miniopenai:gpt-5-nanoopenai:o4-miniopenai:o3anthropic:claude-opus-4-5anthropic:claude-sonnet-4-5anthropic:claude-haiku-4-5

Response

{
  "ok": true,
  "installId": "inst_abc123",
  "agentKey": "triage",
  "model": "openai:gpt-5-mini",
  "routing": "override"
}
DELETE

Reset Agent Model

Clear any model override for an agent, returning it to automatic routing. Envelope will auto-select a model based on the agent's role.

DELETE
/api/installs/:installId/agents/:agentKey/model
API Key Required
curl -X DELETE https://openenvelope.org/api/installs/inst_abc123/agents/triage/model \
  -H "Authorization: Bearer $ENVELOPE_KEY"

Response

{
  "ok": true,
  "installId": "inst_abc123",
  "agentKey": "triage",
  "routing": "auto"
}

Need the full REST reference?

This page covers the endpoints relevant to MCP clients. Platform provisioning, billing, org management, and all other endpoints are documented in the full API reference.

Questions or feedback? Get in touch.