Full REST API reference for AnythingMCP. All endpoints require JWT authentication unless noted.
Get a JWT token via login, then include it in all requests:
TOKEN=$(curl -s http://localhost:4000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","password":"your-password"}' \
| jq -r '.accessToken')
# Use in subsequent requests
curl -H "Authorization: Bearer $TOKEN" http://localhost:4000/api/connectorsInteractive Swagger docs are available at http://localhost:4000/api/docs.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/auth/register |
None | Register (first user becomes Admin) |
| POST | /api/auth/login |
None | Login, returns JWT token |
| POST | /api/auth/invite |
Admin | Invite a user via email |
| GET | /api/auth/invite/verify |
None | Verify an invitation token |
| POST | /api/auth/accept-invite |
None | Accept invitation and create account |
| POST | /api/auth/forgot-password |
None | Request a password reset email |
| POST | /api/auth/reset-password |
None | Reset password with token |
curl -s http://localhost:4000/api/auth/register \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","password":"your-password","name":"Admin User"}'A self-hosted instance answers with an accessToken for the new account. AnythingMCP Cloud answers { "verificationRequired": true, "message": "…" } whether or not the address already has an account and sends the details by email; sign in with the same credentials to continue.
curl -s http://localhost:4000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","password":"your-password"}'Response:
{
"accessToken": "eyJhbGciOiJIUzI1NiIs..."
}curl -s http://localhost:4000/api/auth/invite \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"email":"user@example.com","role":"EDITOR","mcpRoleId":"optional-role-id"}'| Method | Endpoint | Description |
|---|---|---|
| GET | /api/connectors |
List all connectors |
| POST | /api/connectors |
Create a connector |
| GET | /api/connectors/:id |
Get connector with tools |
| PUT | /api/connectors/:id |
Update connector |
| DELETE | /api/connectors/:id |
Delete connector (cascades tools) |
| POST | /api/connectors/:id/test |
Test API connection |
| POST | /api/connectors/:id/import-spec |
Auto-import tools from connector's spec URL |
| POST | /api/connectors/:id/import |
Import tools from any source |
| GET | /api/connectors/export-all |
Export every connector of the organization as JSON (backup) |
| POST | /api/connectors/import-all |
Import connectors from an export, sent as a JSON body |
| GET | /api/connectors/:id/export?format=json|yaml |
Export one connector and its tools as a JSON (default) or YAML file |
| POST | /api/connectors/import |
Import connectors from the text of a JSON or YAML export file (not the same as :id/import) |
| PUT | /api/connectors/:id/env-vars |
Set environment variables |
| POST | /api/connectors/:id/oauth/authorize |
Start OAuth2 authorization flow (returns redirect URL) |
| GET | /api/mcp-oauth/callback |
OAuth2 callback — exchanges code for tokens |
GET /api/connectors/:id/export writes the same envelope as export-all with a
single entry in connectors, so its file can be restored with either import
endpoint. authConfig (OAuth and other stored credentials) is never exported:
re-authorize the connector after importing it. Secret environment variables
and headers are included only for admins signed in to the dashboard or using a
MANAGEMENT_ADMIN key. For other roles, and for any MANAGEMENT_READ key, they
are empty and named in maskedEnvVars / maskedHeaders, and a secret still written in an HTTP
base URL (a webhook token, a key, user:password@) shows as ********; see
Secrets typed into the base URL. Per-tool useProxy, annotation
overrides and role access are not exported.
curl -s "http://localhost:4000/api/connectors/$ID/export?format=yaml" \
-H "Authorization: Bearer $TOKEN" -OJversion: '1.0'
exportedAt: '2026-10-21T10:00:00.000Z'
secretsIncluded: false
connectors:
- name: Acme CRM
type: REST
baseUrl: https://api.acme.test
authType: OAUTH2
envVars:
ACME_API_KEY: ''
maskedEnvVars:
- ACME_API_KEY
tools:
- name: acme_list_contacts
isEnabled: true
endpointMapping:
method: GET
path: /contactsPOST /api/connectors/import takes { "content": "<file text>" }, parses it as
YAML (JSON is accepted too), validates it like import-all and imports into
the caller's organization, skipping connectors whose name already exists.
Viewers get 403. A syntax error returns 400 naming the line and column.
curl -s http://localhost:4000/api/connectors/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d "$(jq -Rs '{content: .}' acme-crm.anythingmcp.yaml)"curl -s http://localhost:4000/api/connectors \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "My API",
"type": "REST",
"baseUrl": "https://api.example.com",
"authType": "BEARER_TOKEN",
"authConfig": {"token": "api-token"},
"specUrl": "https://api.example.com/openapi.json"
}'Connector types: REST, SOAP, GRAPHQL, DATABASE, MCP
Auth types: NONE, API_KEY, BEARER_TOKEN, BASIC_AUTH, OAUTH2, WS_SECURITY, CERTIFICATE, CONNECTION_STRING
# From OpenAPI/Swagger spec URL
curl -s http://localhost:4000/api/connectors/$ID/import-spec \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"specUrl": "https://api.example.com/openapi.json"}'
# From Postman collection
curl -s http://localhost:4000/api/connectors/$ID/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"source": "postman", "url": "https://postman.com/collections/abc123"}'
# From cURL commands
curl -s http://localhost:4000/api/connectors/$ID/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"source": "curl", "content": "curl -X GET https://api.example.com/users"}'
# From GraphQL introspection
curl -s http://localhost:4000/api/connectors/$ID/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"source": "graphql", "url": "https://api.example.com/graphql"}'
# From WSDL
curl -s http://localhost:4000/api/connectors/$ID/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"source": "wsdl", "url": "https://service.example.com/api?wsdl"}'
# From custom JSON
curl -s http://localhost:4000/api/connectors/$ID/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"source": "json", "content": "[{\"name\":\"tool\",\"description\":\"desc\",...}]"}'
# From a HAR file (browser network capture) — the UI slims the file (strips
# response bodies, cookies and credential headers) before upload; do the same
# before sending one by hand.
curl -s http://localhost:4000/api/connectors/$ID/import \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"source": "har", "content": "{\"log\":{\"version\":\"1.2\",\"entries\":[...]}}"}'curl -s -X PUT http://localhost:4000/api/connectors/$ID/env-vars \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"envVars": {"API_SECRET": "value", "TENANT_ID": "abc"}}'| Method | Endpoint | Description |
|---|---|---|
| GET | /api/connectors/:id/tools |
List tools for connector |
| POST | /api/connectors/:id/tools |
Create a single tool |
| POST | /api/connectors/:id/tools/bulk |
Bulk create tools |
| PUT | /api/connectors/:id/tools/:toolId |
Update a tool |
| DELETE | /api/connectors/:id/tools/:toolId |
Delete a tool |
curl -s http://localhost:4000/api/connectors/$ID/tools \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "get_user",
"description": "Get user by ID",
"parameters": {
"type": "object",
"properties": {
"id": {"type": "integer", "description": "User ID"}
},
"required": ["id"]
},
"endpointMapping": {
"method": "GET",
"path": "/users/{id}"
}
}'curl -s http://localhost:4000/api/connectors/$ID/tools/bulk \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"tools": [...]}'See Tool Definition Format for the full schema.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/mcp-servers |
List MCP server configurations |
| POST | /api/mcp-servers |
Create MCP server config |
| PUT | /api/mcp-servers/:id |
Update MCP server config |
| DELETE | /api/mcp-servers/:id |
Delete MCP server config |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/audit/invocations |
List invocations (with filters) |
| GET | /api/audit/stats |
Get invocation stats (24h, 7d, total) |
| GET | /api/audit/tool-performance |
Per-tool latency percentiles, failure rates and last recorded errors |
# Filter by tool name
curl -s "http://localhost:4000/api/audit/invocations?toolName=get_user" \
-H "Authorization: Bearer $TOKEN"
# Filter by date range
curl -s "http://localhost:4000/api/audit/invocations?from=2026-01-01&to=2026-01-31" \
-H "Authorization: Bearer $TOKEN"curl -s http://localhost:4000/api/audit/stats \
-H "Authorization: Bearer $TOKEN"Response:
{
"last24h": 142,
"last7d": 1053,
"total": 8721
}The Tool performance table on /analytics shows calls, failure rate,
p50/p95/p99 latency and the last recorded error for each tool and MCP server.
Its own time selector defaults to the last 24 hours; connector and MCP server
filters narrow the results. This view is available on Cloud and self-hosted
editions, using the invocation history still retained by the instance.
curl -s "http://localhost:4000/api/audit/tool-performance?hours=24&connectorId=<connectorId>&mcpServerId=<serverId>&limit=25&offset=0" \
-H "Authorization: Bearer $TOKEN"All results belong to the signed-in user's organization. Optional parameters:
| Parameter | Default | Bounds / meaning |
|---|---|---|
hours |
24 |
Integer from 1 to 2160 (90 days), rolling window |
connectorId |
All connectors | A connector in the user's organization |
mcpServerId |
All servers | An MCP server in the user's organization |
limit |
25 |
Integer from 1 to 100 |
offset |
0 |
Non-negative integer; increase by limit for the next page |
Response:
{
"items": [{
"toolId": "tool-1",
"toolName": "search_orders",
"connectorId": "connector-1",
"connectorName": "Orders",
"mcpServerId": null,
"mcpServerName": null,
"calls": 10,
"errors": 2,
"errorRate": 20,
"latencySampleCount": 8,
"p50Ms": 120,
"p95Ms": 430,
"p99Ms": 486,
"lastError": "Request timed out",
"lastErrorAt": "2026-11-04T10:00:00.000Z"
}],
"hasMore": false
}errors includes both ERROR and TIMEOUT; errorRate is a percentage.
Counts include the repeated failures represented by each stored record.
Percentiles use only stored, non-null duration samples, without repeating the
first duration for every deduplicated failure. latencySampleCount reports
that sample count; absent latencies are null, while 0 is a valid duration.
Repeated failures retain their first recorded server, so server attribution
and the last recorded error reflect the saved history rather than every
individual request. A null server means direct calls without a recorded MCP
server. Same-name tools from different connectors remain separate.
Rows are ordered by call count, with stable identity-based tie-breaking.
hasMore indicates whether another page exists. The rolling window may change
between page requests as new calls arrive.
When viewing an audit log entry in the dashboard (/logs), click Copy as cURL in the expanded row to copy a command that replays the recorded MCP tools/call against the server's endpoint:
curl -sS -X POST 'http://localhost:4000/mcp/<serverId>' \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2025-06-18" \
-H "X-API-Key: $AMCP_MCP_API_KEY" \
--data-binary @- <<'JSON'
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}
JSONExport your key as AMCP_MCP_API_KEY (or AMCP_ACCESS_TOKEN when the server operates in OAuth2 mode) to run the command directly from your terminal. Arguments whose names look like credentials (passwords, tokens, keys) are replaced with [REDACTED], and the command then starts with a comment saying so: fill them in before running it.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/roles |
List all roles |
| POST | /api/roles |
Create a custom role |
| PUT | /api/roles/:id |
Update a role |
| DELETE | /api/roles/:id |
Delete a role |
| GET | /api/roles/:id/tools |
List tool access for a role |
| PUT | /api/roles/:id/tools |
Set tool access whitelist |
| PUT | /api/roles/:id/tools/:toolId/rate-limit |
Update rate limits on an existing tool grant |
| GET | /api/roles/members |
List members with every MCP role they hold and the connectors those roles reach |
| GET | /api/roles/assignments/:userId |
List a member's MCP roles, with where each comes from |
| PUT | /api/roles/assignments/:userId |
Replace a member's manual MCP roles |
| PUT | /api/roles/assign/:userId |
Deprecated: set one MCP role. Use PUT /api/roles/assignments/:userId |
# 1. Create role
ROLE_ID=$(curl -s http://localhost:4000/api/roles \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "Sales Team", "description": "Access to CRM tools only"}' \
| jq -r '.id')
# 2. Set tool whitelist
curl -s -X PUT http://localhost:4000/api/roles/$ROLE_ID/tools \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"toolIds": ["tool-id-1", "tool-id-2", "tool-id-3"]}'A member can hold several MCP roles and may call the union of their tools: each role adds tools, none takes any away. A role comes from one of two sources:
manual: set by an admin, under Settings → Roles or withPUT /api/roles/assignments/:userId.- the single sign-on group sync (for example
entra): set by the provider's role mappings (SSO guide). Change these in the mappings, not on the member.
PUT /api/roles/assignments/:userId replaces only the member's manual
roles in your workspace; roles from group sync stay.
curl -s -X PUT http://localhost:4000/api/roles/assignments/$USER_ID \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"roleIds": ["'$ROLE_ID'"]}'GET /api/roles/members returns every member of your workspace with all their
roles (roles[]: roleId, roleName, source, and global for a grant that
applies in every workspace) and connectors, the connectors those roles reach.
connectors is null when roles do not limit the member: a workspace ADMIN,
or a member with no role while no role of the workspace has a tool list.
GET /api/users also returns all roles of each member in mcpRoles; its
mcpRoleId and mcpRole fields are deprecated and hold one role at most.
An administrator can set optional minute and hour limits on an existing
role/tool grant, under Settings → Roles → Manage tools or through the API.
GET /api/roles/:id/tools returns callsPerMinute and callsPerHour on each
grant.
curl -s -X PUT "http://localhost:4000/api/roles/$ROLE_ID/tools/tool-id-1/rate-limit" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"callsPerMinute": 100, "callsPerHour": 10000}'Each value must be a positive integer (at most 2,147,483,647), or null for
unlimited. Omitted fields keep their current value. New grants start unlimited.
Updating the tool whitelist preserves limits on retained grants; removing a
grant deletes its policy. System roles cannot be modified. Configuration is
restricted to grants and tools in the administrator's workspace.
Limits are per principal and tool within a workspace, shared across MCP
servers. Each user has one budget per tool, shared by their sessions and all of
their API keys, so creating another key does not raise it. Limits are not
shared by every member of a role. Nested Code Mode amcp.run calls use the
same budget as direct calls. A saved code tool can also have its own limit.
For multiple granting roles, resolve each window independently: the largest
value wins, and null means unlimited for that window. For example, a role
granting 100/min and 200/hour combined with one granting 10/min and 10,000/hour
allows 100/min and 10,000/hour, even though neither role grants that pair
alone. A granting role with both windows unlimited removes the per-tool limit.
Workspace ADMINs and unrestricted members with no MCP role in a workspace
without whitelists have no per-tool limit; the existing principal limiter
still applies to them.
Both configured windows must allow the call. Each fixed window starts on its
first admitted call and expires after 60 or 3,600 seconds respectively. Admitted
calls count even when answered from the response cache or when the upstream
fails. Refused calls do not consume either budget or extend the windows. A
refusal is an MCP tool result with isError: true; its text contains an error
naming the tool and reached limit, plus retryAfter in seconds. If both limits
are reached, the retry time is the longer wait. No upstream call is made.
Cloud and self-hosted use the same implementation. With Redis configured, admission and expiry are atomic across replicas. If configured Redis is unavailable, calls fail open with a warning; there is no process-local fallback. Without Redis configured, counters are process-local, reset on restart, and are not shared across replicas. Local storage is bounded to 10,000 principal/tool/workspace buckets; expired buckets are reclaimed when capacity is needed. When full, calls for new buckets are allowed without tracking and a warning is logged at most once a minute. Existing buckets remain enforced.
Workspaces without any configured limits skip rate-policy lookups using a bounded, five-second presence cache. Configuration changes invalidate this cache immediately on the instance handling the edit; other replicas observe new limits within five seconds. Positive policies are still read fresh per call, so cached presence never replaces the caller's current role policy.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/settings/member-visibility |
Any member: { mode, restrictedForMe } of the current workspace |
| PUT | /api/admin/settings/member-visibility |
Admin: set { "mode": "open" } or { "mode": "restricted" } |
In a workspace set to restricted, a member who is not an admin gets only
their own calls from the audit endpoints, only the connectors their roles
reach, only the MCP servers they own, and 404 for the others. A connector they can see but do not
own comes back in a reduced view marked memberView: true: id, name,
type, icon, isActive, credentialScope, setupStatus, authStatus,
authStatusCode, and of each allowed tool id, name, description and
isEnabled; no address, variables, headers, instructions or endpoint
mappings. Admins and open workspaces (the default) see everything. What each endpoint returns, how it combines with
roles and SSO group mapping, and what stays visible:
member visibility.
amcp api GET /api/settings/member-visibility
amcp api PUT /api/admin/settings/member-visibility --data '{"mode":"restricted"}' --yes| Method | Endpoint | Description |
|---|---|---|
| GET | /api/mcp-keys |
List your MCP API keys |
| POST | /api/mcp-keys |
Generate a new MCP API key |
| POST | /api/mcp-keys/:id/revoke |
Revoke (deactivate) an MCP API key |
| DELETE | /api/mcp-keys/:id |
Delete an MCP API key |
curl -s http://localhost:4000/api/mcp-keys \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "My Claude Desktop Key", "mcpServerId": "optional-server-id"}'A key created with mcpServerId (as the dashboard does, from a server's page)
works only for that server: on /mcp/<that server>, and on the shared /mcp
with that server's tools. Other servers answer 403. The server must be one of
an organization you belong to, and deleting it deactivates its keys. A key
created without mcpServerId reaches every server of your organization.
The repository includes the amcp CLI for logging
in with an MCP API key, listing and describing tools, and calling them on a
specific server. Build it with
npm run build -w packages/cli, then run:
node packages/cli/dist/index.js login --url http://localhost:4000 --server YOUR_SERVER_ID
node packages/cli/dist/index.js tools ls
node packages/cli/dist/index.js tools describe YOUR_TOOL_NAME
node packages/cli/dist/index.js tools call YOUR_TOOL_NAME --args '{"id":"123"}' --jsonThe CLI constructs /mcp/<serverId> from the instance URL and server ID.
The /api/* endpoints in this reference use a JWT, while the CLI connects to
MCP with an MCP API key.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/settings/smtp |
Get SMTP configuration |
| PUT | /api/settings/smtp |
Update SMTP configuration |
| POST | /api/settings/smtp/test |
Test SMTP connection |
| GET | /api/settings/footer-links |
Get footer link configuration |
| PUT | /api/settings/footer-links |
Update footer links |
curl http://localhost:4000/healthNo authentication required.