API Overview

The MCP Gateway API is a RESTful JSON API. In the boilerplate it ships with authentication test endpoints and full webhook endpoint management — extend it with your own resources as you build your domain.

Interactive reference: The full API specification with request/response schemas and a built-in "Try it out" tool lives at the interactive API reference. The raw OpenAPI spec is at /api/v1/openapi.yaml. This page is a narrative overview -- use the interactive reference for endpoint-level details.

Base URL

All API endpoints are available at:

https://mcp.agentic-accounting.com/api/v1/

Authentication

Every request must include an Authorization header with a Bearer token:

Authorization: Bearer YOUR_API_KEY

There are two ways to get a token:

API keys -- workspace owners create keys under API Keys in the sidebar. Pick the scopes the key needs; the key is shown once at creation and is a long-lived Bearer token — paste it directly into the Authorization header, no token exchange required. Keys can be revoked at any time.
OAuth 2.0 authorization code grant -- for third-party applications that act on behalf of a user. MCP Gateway is a full OAuth 2.0 provider with authorize, token, revoke, and introspect endpoints under /oauth, dynamic client registration (RFC 7591) at POST /oauth/register, and discovery documents at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. During authorization the user picks which workspace to connect, and the issued token is scoped to it.

API access requires the api-access entitlement on the workspace's plan; without it, requests return 403 with type forbidden.

Scopes

Tokens carry scopes that limit which endpoints they can call:

Scope	Grants access to
`profile:read`	Baseline read access — request this for connections that only need to identify the workspace
`webhooks:manage`	Full CRUD on webhook endpoints, plus test deliveries

GET /api/v1/ping and GET /api/v1/me accept any valid token, regardless of scope. Calling an endpoint without the required scope returns 403 with type insufficient_scope.

Quick start

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://mcp.agentic-accounting.com/api/v1/ping

{
  "status": "ok",
  "account": { "id": "…", "name": "Your Workspace" },
  "token": { "application": "My integration", "scopes": ["webhooks:manage"] }
}

Available endpoints

Endpoint	Description	Required scope
`GET /api/v1/ping`	Health check; returns account and token metadata	any valid token
`GET /api/v1/me`	The authenticated workspace's id, name, slug, and token scopes	any valid token
`GET /api/v1/webhook_endpoints`	List webhook endpoints	`webhooks:manage`
`GET /api/v1/webhook_endpoints/:id`	Get an endpoint with its 10 most recent deliveries	`webhooks:manage`
`POST /api/v1/webhook_endpoints`	Create an endpoint; the response includes the signing secret (only time it's returned)	`webhooks:manage`
`PATCH /api/v1/webhook_endpoints/:id`	Update an endpoint	`webhooks:manage`
`DELETE /api/v1/webhook_endpoints/:id`	Delete an endpoint and its delivery history	`webhooks:manage`
`POST /api/v1/webhook_endpoints/:id/test`	Send a test `ping` event and return the delivery result	`webhooks:manage`

See Webhooks for payload formats and signature verification.

Rate limits

All authenticated API requests (including the MCP server) are rate-limited per token:

60 requests per minute
500 requests per hour

Every API response includes:

Header	Description
`X-RateLimit-Limit`	Maximum requests in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you exceed a limit you receive 429 Too Many Requests with a Retry-After header and an error envelope of type rate_limited.

Error format

All errors use a consistent JSON envelope:

{
  "error": {
    "type": "not_found",
    "message": "Couldn't find WebhookEndpoint with id=..."
  }
}

Type	Status	Meaning
`authentication_required`	401	Missing or malformed `Authorization` header
`invalid_token`	401	Token is unknown, revoked, or its application was revoked
`token_expired`	401	Token has expired (OAuth flows; refresh it)
`insufficient_scope`	403	Token lacks the required scope
`forbidden`	403	Plan does not include API access
`not_found`	404	Resource doesn't exist in this workspace
`invalid_request`	400	Malformed request body or missing parameter
`validation_error`	422	Attributes failed validation; the message lists the failures
`rate_limited`	429	Too many requests

Going further

Webhooks -- receive real-time notifications when events happen in your workspace
MCP server -- let AI assistants like Claude work with your workspace over the same tokens and scopes
Interactive API reference -- schemas, examples, and a try-it-out console