API Reference
The complete MCP Stack REST API, grouped by resource — every method, path, and request body, with copyable signatures and runnable examples.
The MCP Stack REST API manages organizations, MCP servers, gateways, and agents. The CLI wraps these same endpoints.
Each group below lists every endpoint in that resource. Scan the method and description; copy the exact signature; expand a row for a runnable curl example.
Base URL: https://api.mcpstack.com
Auth: send an OAuth access token or a service-account key as a bearer token. Service-account keys (mcpstack_sk_…) are also accepted in the X-API-Key header.
Authorization: Bearer <token>
X-API-Key: mcpstack_sk_...Organization scope: most endpoints live under one organization root. Throughout this page that root is shown inline as /api/v1/organizations/{orgId}, so every signature is complete and unambiguous. A handful of endpoints sit above the org root and are shown with their full /api/v1/... path.
Errors: a 401 means the request was not authenticated; a 403 means the identity authenticated but lacks the required grant on that resource.
export BASE="https://api.mcpstack.com"
export TOKEN="mcpstack_sk_..."
# List the organizations the token can access
curl -sS --fail-with-body "$BASE/api/v1/organizations" \
-H "Authorization: Bearer $TOKEN"Identity, membership, service-account keys, and permission checks.
/api/v1/organizationsList organizations the token can access./api/v1/organizationsCreate an organization. Body: `{ name, slug }`.Create an organization. Body: `{ name, slug }`.{
"name": "Acme",
"slug": "acme"
}{
"id": "org_7Hf3kQ2",
"slug": "acme",
"name": "Acme",
"planTier": "free",
"mcpServerCount": 0,
"memberCount": 1,
"createdOn": "2026-05-29T18:20:11Z",
"publicMcpGuidesEnabled": true
}/api/v1/organizations/{orgId}Get the current organization./api/v1/organizations/{orgId}Update organization details./api/v1/organizations/{orgId}Delete the organization. Admin only./api/v1/organizations/{orgId}/membersList active members./api/v1/organizations/{orgId}/members/{principalId}Change a member's role. Body: `{ role }`./api/v1/organizations/{orgId}/members/{principalId}Remove a member./api/v1/organizations/{orgId}/invitationsList pending invitations./api/v1/organizations/{orgId}/invitationsInvite a teammate. Body: `{ email, role }`.Invite a teammate. Body: `{ email, role }`.role is one of admin, developer, or viewer.
{
"email": "teammate@example.com",
"role": "developer"
}{
"id": "inv_3Kd9twP",
"organizationId": "org_7Hf3kQ2",
"organizationName": "Acme",
"email": "teammate@example.com",
"role": "developer",
"status": "pending",
"inviteUrl": "https://app.mcpstack.com/invitations/inv_3Kd9twP",
"createdAt": "2026-05-29T18:20:11Z",
"expiresAt": "2026-06-05T18:20:11Z",
"lastSentAt": "2026-05-29T18:20:11Z",
"acceptedAt": null,
"acceptedByUserId": null,
"revokedAt": null,
"revokedReason": null,
"lastSendError": null
}curl -sS --fail-with-body -X POST \
"$BASE/api/v1/organizations/$ORG_ID/invitations" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "email": "teammate@example.com", "role": "developer" }'/api/v1/organizations/{orgId}/invitations/{invitationId}/resendResend an invitation email./api/v1/organizations/{orgId}/invitations/{invitationId}/revokeRevoke an invitation. Body: `{ reason? }`./api/v1/organizations/{orgId}/api-keysList service-account keys./api/v1/organizations/{orgId}/api-keys/rolesList roles assignable to keys./api/v1/organizations/{orgId}/api-keysCreate a service-account key. The full secret is returned only here.Create a service-account key. The full secret is returned only here.roleKey defaults to viewer. The fullKey (mcpstack_sk_…) is returned once on creation and never again.
{
"name": "automation-bot",
"roleKey": "developer"
}{
"id": "key_9Lm2vRs",
"name": "automation-bot",
"clientId": "mcpstack_sk_3f8ad12c",
"fullKey": "mcpstack_sk_3f8ad12c_b7e1d9a4c0f24e6fa1c8d3b2e5079a6f",
"createdAt": "2026-05-29T18:20:11Z",
"expiresAt": null,
"roleKey": "developer",
"roleName": "Developer"
}curl -sS --fail-with-body -X POST \
"$BASE/api/v1/organizations/$ORG_ID/api-keys" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "name": "automation-bot", "roleKey": "developer" }'/api/v1/organizations/{orgId}/api-keys/{keyId}Revoke a service-account key./api/v1/organizations/{orgId}/authorization/checkCheck organization-level permissions./api/v1/organizations/{orgId}/authorization/check-entitiesCheck permissions on specific resources.The core resource: create a server from an OpenAPI spec, then shape, verify, deploy, and operate it.
/api/v1/organizations/{orgId}/mcp-serversList MCP servers./api/v1/organizations/{orgId}/mcp-serversCreate a server. Hosted servers publish to MCP Stack Host automatically.Create a server. Hosted servers publish to MCP Stack Host automatically.Store a private spec inline with openApiSpecJson (JSON or YAML text); the file does not need to be reachable on the public internet. Set openApiSpecSource to upload (or url with openApiSpecUrl).
SPEC="$(jq -Rs . < openapi.yaml)"
curl -sS --fail-with-body -X POST \
"$BASE/api/v1/organizations/$ORG_ID/mcp-servers" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d @- <<JSON
{
"name": "Support API",
"slug": "support-api",
"kind": "generated_openapi",
"runtimeType": "generated_worker",
"openApiSpecJson": $SPEC,
"openApiSpecSource": "upload",
"openApiSpecFileName": "openapi.yaml"
}
JSON{
"id": "mcp_5Qp8wYz",
"organizationId": "org_7Hf3kQ2",
"slug": "support-api",
"gatewayPublicId": null,
"name": "Support API",
"description": null,
"status": "draft",
"kind": "generated_openapi",
"runtimeType": "generated_worker",
"openApiSpecUrl": null,
"totalInvocations": 0,
"toolCount": 12,
"createdOn": "2026-05-29T18:20:11Z",
"hasOpenApiSpec": true,
"openApiSpecSource": "upload",
"openApiSpecFileName": "openapi.yaml",
"openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
"hasGateway": false,
"toolsManaged": true,
"gateway": null,
"catalogStatus": "unknown",
"catalogError": null,
"installGuideEnabled": true
}/api/v1/organizations/{orgId}/mcp-servers/{serverId}Get a server, including its tools.Get a server, including its tools.The tools array carries the toolId values used by the tool and smoke-test endpoints.
{
"id": "mcp_5Qp8wYz",
"organizationId": "org_7Hf3kQ2",
"slug": "support-api",
"name": "Support API",
"status": "running",
"kind": "generated_openapi",
"runtimeType": "generated_worker",
"hasOpenApiSpec": true,
"totalInvocations": 1840,
"createdOn": "2026-05-29T18:20:11Z",
"tools": [
{
"id": "tool_2Ab7nLk",
"toolKey": "createTicketNote",
"displayName": "Create ticket note",
"httpMethod": "POST",
"httpPath": "/tickets/{id}/notes",
"isEnabled": true
}
],
"hasGateway": false,
"toolsManaged": true,
"installGuideEnabled": true
}/api/v1/organizations/{orgId}/mcp-servers/{serverId}Update settings or replace the spec./api/v1/organizations/{orgId}/mcp-servers/{serverId}Delete a server. Hosted runtime cleanup is automatic./api/v1/organizations/{orgId}/mcp-servers/{serverId}/configGet the resolved server configuration./api/v1/organizations/{orgId}/mcp-servers/{serverId}/analyticsGet usage analytics./api/v1/organizations/{orgId}/mcp-servers/{serverId}/logsPage through request logs./api/v1/organizations/{orgId}/mcp-servers/{serverId}/openapiReplace the stored OpenAPI spec./api/v1/organizations/{orgId}/mcp-servers/{serverId}/openapi/refreshRe-fetch a URL-backed spec and re-import tools./api/v1/organizations/{orgId}/mcp-servers/{serverId}/discover-toolsRe-import tools from the current spec./api/v1/organizations/{orgId}/mcp-servers/{serverId}/tools/{toolId}Edit one tool.Edit one tool.toolId comes from the tools array on the server detail response. Fields: isEnabled, displayName, descriptionOverride, instructions, whenToUse, whenNotToUse.
{
"isEnabled": true,
"displayName": "Create ticket note",
"instructions": "Use only after the user confirms the ticket id and note body."
}{
"id": "tool_2Ab7nLk",
"name": "create_ticket_note",
"toolKey": "createTicketNote",
"displayName": "Create ticket note",
"description": "Append a note to a support ticket.",
"httpMethod": "POST",
"httpPath": "/tickets/{id}/notes",
"isEnabled": true,
"toolNamingVersion": 2,
"source": "generated_openapi",
"isManaged": true,
"instructions": "Use only after the user confirms the ticket id and note body.",
"whenToUse": null,
"whenNotToUse": null
}curl -sS --fail-with-body -X PATCH \
"$BASE/api/v1/organizations/$ORG_ID/mcp-servers/$SERVER_ID/tools/$TOOL_ID" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"isEnabled": true,
"displayName": "Create ticket note",
"instructions": "Use only after the user confirms the ticket id and note body."
}'/api/v1/organizations/{orgId}/mcp-servers/{serverId}/toolsBulk-replace tool settings. Body: an array of tool patches./api/v1/organizations/{orgId}/mcp-servers/{serverId}/endpointsGet the enabled endpoint set./api/v1/organizations/{orgId}/mcp-servers/{serverId}/endpointsUpdate which endpoints are exposed./api/v1/organizations/{orgId}/mcp-servers/{serverId}/auth-configGet the runtime auth configuration./api/v1/organizations/{orgId}/mcp-servers/{serverId}/auth-configUpdate runtime auth./api/v1/organizations/{orgId}/mcp-servers/{serverId}/auth-discoveryProbe the upstream API's auth requirements./api/v1/organizations/{orgId}/mcp-servers/{serverId}/hosting-checksRun DNS, TLS, routing, runtime, and tools/list checks.Run DNS, TLS, routing, runtime, and tools/list checks.Pass ?environment=prod to target a specific environment.
curl -sS --fail-with-body -X POST \
"$BASE/api/v1/organizations/$ORG_ID/mcp-servers/$SERVER_ID/hosting-checks?environment=prod" \
-H "Authorization: Bearer $TOKEN"/api/v1/organizations/{orgId}/mcp-servers/{serverId}/mcp-smoke/tools-listList tools over MCP against the live runtime./api/v1/organizations/{orgId}/mcp-servers/{serverId}/mcp-smoke/tools/{toolName}/callInvoke a tool over MCP. Body: `{ arguments }`./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deploymentGet the current deployment./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment/logsGet hosted runtime logs./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deploymentsList deployment history./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployments/{deploymentId}Get one deployment./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-configGet the deployment config./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-configUpdate the deployment config./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-operationsList publish/deployment operations./api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-operations/{operationId}Get one operation's status.Attach a customer-owned hostname to a hosted server. See custom domains for the staged DNS workflow.
/api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domainGet custom-domain status./api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domain/validateStart validation; returns the ownership TXT record. Body: `{ hostName, environment? }`./api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domain/confirm-ownershipConfirm ownership after the TXT record resolves./api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domain/finalizeFinalize routing once CNAME/TXT records propagate./api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domainRemove the custom domain./api/v1/organizations/{orgId}/mcp-servers/{serverId}/gatewayGet the server's gateway attachment./api/v1/organizations/{orgId}/mcp-servers/{serverId}/gatewayAttach a gateway. Body: `{ gatewayId, publicId? }`./api/v1/organizations/{orgId}/mcp-servers/{serverId}/gatewayDetach the gateway.Reusable OAuth/discovery profiles that front one or more hosted servers.
/api/v1/organizations/{orgId}/gatewaysList gateways./api/v1/organizations/{orgId}/gatewaysCreate a gateway. Body: `{ name, provider, authorizationServerUrl, clientId, resource, scopes[] }`./api/v1/organizations/{orgId}/gateways/{gatewayId}Get a gateway./api/v1/organizations/{orgId}/gateways/{gatewayId}Update a gateway./api/v1/organizations/{orgId}/gateways/{gatewayId}Delete a gateway./api/v1/organizations/{orgId}/gateways/{gatewayId}/serversList servers attached to a gateway./api/v1/organizations/{orgId}/gateways/{gatewayId}/grantsList OAuth grants issued through a gateway./api/v1/organizations/{orgId}/gateways/{gatewayId}/logsGet gateway request logs.Create agents, inspect usage and conversations, and manage embed keys and budgets.
/api/v1/organizations/{orgId}/agent-model-optionsList available models./api/v1/organizations/{orgId}/agentsList agents./api/v1/organizations/{orgId}/agentsCreate an agent. Body: `{ name, mcpServerIds[], … }`./api/v1/organizations/{orgId}/agents/{agentId}Get an agent./api/v1/organizations/{orgId}/agents/{agentId}Update an agent./api/v1/organizations/{orgId}/agents/{agentId}Delete an agent./api/v1/organizations/{orgId}/agents/{agentId}/usageGet usage and cost for an agent./api/v1/organizations/{orgId}/agents/{agentId}/usage/usersGet per-user usage./api/v1/organizations/{orgId}/agents/{agentId}/usage/llm-callsGet LLM call logs./api/v1/organizations/{orgId}/embed-usageGet embedded-agent usage across the organization./api/v1/organizations/{orgId}/agents/{agentId}/conversationsList an agent's conversations./api/v1/organizations/{orgId}/agents/{agentId}/conversations/{conversationId}Get a conversation./api/v1/organizations/{orgId}/agents/{agentId}/conversations/{conversationId}/messagesGet a conversation's messages.Cap spend at the agent level and per embedded user.
/api/v1/organizations/{orgId}/agents/{agentId}/budgetSet the agent's default budget policy.Set the agent's default budget policy.Fields: monthlyBudgetUsd (required when enabled), defaultUserBudgetUsd, anonymousMonthlyBudgetUsd, currency (default USD), enabled.
{
"enabled": true,
"monthlyBudgetUsd": 10000,
"defaultUserBudgetUsd": 5
}{
"monthlyBudgetUsd": 10000,
"defaultUserMonthlyBudgetUsd": 5,
"anonymousMonthlyBudgetUsd": null,
"currency": "USD",
"allocationMode": "shared",
"resetDayOfMonthUtc": 1,
"currentMonthSpendUsd": 0,
"remainingBudgetUsd": 10000,
"trackedUserCount": 0,
"assignedUserCount": 0,
"assignedBudgetUsd": 0,
"enabled": true
}curl -sS --fail-with-body -X PATCH \
"$BASE/api/v1/organizations/$ORG_ID/agents/$AGENT_ID/budget" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "enabled": true, "monthlyBudgetUsd": 10000, "defaultUserBudgetUsd": 5 }'/api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budgetSet one embedded user's monthly cap. Body: `{ monthlyBudgetUsd }`./api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budgetGet one embedded user's budget./api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budgetRemove an embedded user's override./api/v1/organizations/{orgId}/agents/{agentId}/embed-keysList embed keys./api/v1/organizations/{orgId}/agents/{agentId}/embed-keysCreate an embed key. The public key is returned once./api/v1/organizations/{orgId}/agents/{agentId}/embed-keys/{keyId}Revoke an embed key./api/v1/organizations/{orgId}/agents/{agentId}/verified-domainsList verified embed domains./api/v1/organizations/{orgId}/agents/{agentId}/verified-domainsAdd a domain to verify for embedding./api/v1/organizations/{orgId}/agents/{agentId}/verified-domains/{domainId}/confirmConfirm a domain after the DNS record resolves./api/v1/organizations/{orgId}/ai-credits/summaryGet the AI-credit balance./api/v1/organizations/{orgId}/ai-credits/ledgerGet the AI-credit ledger./api/v1/organizations/{orgId}/ai-credits/checkout-sessionStart an AI-credit checkout./api/v1/organizations/{orgId}/ai-credits/checkout-session/{sessionId}/syncReconcile an AI-credit checkout session./api/v1/organizations/{orgId}/mcp-hosting/usageGet hosted-runtime usage./api/v1/organizations/{orgId}/mcp-hosting/billing/checkout-sessionStart a hosting checkout./api/v1/organizations/{orgId}/mcp-hosting/billing/checkout-session/{sessionId}/syncReconcile a hosting checkout session./api/v1/organizations/{orgId}/billing/portal-sessionOpen the billing portal.These sit above the organization root.
/api/v1/dashboard/statsGet dashboard summary stats./api/v1/dashboard/analyticsGet aggregated analytics./api/v1/auth/meGet the current user./api/v1/cli/configGet CLI bootstrap config. No auth required./api/v1/cli/whoamiIdentify the caller behind a token or key.These endpoints are intentionally out of scope for this reference: system-admin (/api/v1/admin/*), the OAuth gateway flow (/api/v1/gateway/{publicId}/*), and embed-key chat (/api/v1/chat).