Skip to content

Latest commit

 

History

History
611 lines (492 loc) · 23 KB

api-reference.md

File metadata and controls

611 lines (492 loc) · 23 KB

API Reference

Full REST API reference for AnythingMCP. All endpoints require JWT authentication unless noted.

Back to README


Authentication

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/connectors

Interactive Swagger docs are available at http://localhost:4000/api/docs.


Auth Endpoints

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

Register

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.

Login

curl -s http://localhost:4000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"your-password"}'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Invite User (Admin)

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"}'

Connector Endpoints

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

Export and Import a Connector

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" -OJ
version: '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: /contacts

POST /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)"

Create Connector

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

Import Tools

# 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\":[...]}}"}'

Set Environment Variables

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"}}'

Tool Endpoints

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

Create 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}"
    }
  }'

Bulk Create Tools

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.


MCP Server Endpoints

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

Audit Endpoints

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

Query Invocations

# 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"

Get Stats

curl -s http://localhost:4000/api/audit/stats \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "last24h": 142,
  "last7d": 1053,
  "total": 8721
}

Tool Performance

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.

Replay a Tool Call

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":{...}}}
JSON

Export 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.


Roles & Access Control

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

Create Role with Tool Whitelist

# 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"]}'

Assign roles to members

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 with PUT /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.

Per-tool rate limits

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.

Member visibility

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

MCP API Keys

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

Generate 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.

CLI

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"}' --json

The 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.


Site Settings (Admin)

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

Health Check

curl http://localhost:4000/health

No authentication required.


Back to README | Tool Definition Format | Deployment Guide