MCP

Check your MCP availability, monitor monthly usage, and review or export your personal MCP activity.

Base path: /api/v1/mcp

MCP Clients base path: /mcp

Authentication and Access

Use an OAuth bearer token from normal user login. All five endpoints are restricted to the authenticated user in the current tenant. They require no additional permission scopes and reject API-key authentication and impersonation. Administrators cannot use them to read another user's activity.

These endpoints remain available when MCP is disabled or the user lacks mcp:mcp:use. They consume no monthly MCP calls. Responses include Cache-Control: no-store; ordinary HTTP rate limits still apply.

Get MCP Configuration

GET /api/v1/mcp/configuration

Requires Authentication - Normal user login. Scopes: none.

Return effective availability and the user's current limits. Server and tenant MCP settings both default to false. A disabled configuration is a successful 200 OK response with enabled: false.

curl "https://koldan.dixilang.com/api/v1/mcp/configuration" \
  -H "Authorization: Bearer $JWT"

McpConfigurationResponse

{
  "enabled": false,
  "callsPerMinute": 30,
  "monthlyCalls": 2000
}

See Common Errors for authentication and rate-limit responses.

Get MCP Usage

GET /api/v1/mcp/usage

Requires Authentication - Normal user login. Scopes: none.

Return usage for the current UTC calendar month, shared across all of the user's API keys. Each permitted MCP tool invocation consumes one call, including invocations that subsequently fail. Initialization, discovery, and these account API reads consume no monthly calls.

curl "https://koldan.dixilang.com/api/v1/mcp/usage" \
  -H "Authorization: Bearer $JWT"

McpUsageResponse

{
  "used": 42,
  "limit": 2000,
  "remaining": 1958,
  "resetsAt": "2026-10-01T00:00:00Z"
}

Revoking a key, disabling MCP, or expiring activity history does not reset monthly usage. Use this endpoint for accounting; retained activity may cover a shorter period.

See Common Errors for authentication and rate-limit responses.

List MCP Activity

GET /api/v1/mcp/audit

Requires Authentication - Normal user login. Scopes: none.

List personal MCP calls, newest first. The response is a JSON array, with no total or nextPage envelope. Start at page 0 and increment page until fewer than size items are returned. New calls can shift pages while browsing.

Query Parameters

curl --get "https://koldan.dixilang.com/api/v1/mcp/audit" \
  -H "Authorization: Bearer $JWT" \
  --data-urlencode "tool=list_files" \
  --data-urlencode "from=2026-09-01T00:00:00Z" \
  --data-urlencode "until=2026-10-01T00:00:00Z" \
  --data-urlencode "page=0" \
  --data-urlencode "size=20"

McpAuditCallResponse[]

[
  {
    "callId": "550e8400-e29b-41d4-a716-446655440000",
    "occurredAt": "2026-09-21T08:15:00Z",
    "apiKeyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "toolName": "list_files",
    "protocolMethod": "tools/call",
    "outcome": "PREPARED",
    "quotaCharged": true,
    "durationMs": 24,
    "responseBytes": 1240,
    "incomplete": false
  }
]

See Common Errors for authentication and rate-limit responses.

Get MCP Call Details

GET /api/v1/mcp/audit/{callId}

Requires Authentication - Normal user login. Scopes: none.

Return the retained event timeline for one of your calls, in recorded order. Events include receipt, identification, admission, and response preparation or failure. A call may have fewer events if rejected early or left incomplete.

Path Parameters

curl "https://koldan.dixilang.com/api/v1/mcp/audit/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $JWT"

McpAuditEventResponse[]

The timeline contains no transcript, translation, or summary bodies, credentials, raw headers, arbitrary search text, returned objects, or lists of returned resource identifiers. When present, subject is the input identifier of the object or parent resource on which the tool operated; access must still be checked through that resource's service API.

[
  {
    "id": 103,
    "callId": "550e8400-e29b-41d4-a716-446655440000",
    "occurredAt": "2026-09-21T08:15:00.010Z",
    "eventType": "ADMITTED",
    "correlationId": "550e8400-e29b-41d4-a716-446655440000",
    "apiKeyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "protocolMethod": "tools/call",
    "protocolVersion": "2025-11-25",
    "toolName": "list_files",
    "schemaVersion": 1,
    "outcome": "ADMITTED",
    "charged": true,
    "durationMs": 10,
    "metadata": {}
  }
]

See Common Errors for authentication and rate-limit responses.

Export MCP Activity

GET /api/v1/mcp/audit/export

Requires Authentication - Normal user login. Scopes: none.

Download up to 1,000 matching call summaries, newest first. The export uses the same apiKeyId, tool, outcome, from, and until filters as the activity list. It does not include detailed event timelines.

Export Parameters

There is no page parameter or total-count field. An export containing exactly size rows may be truncated. Narrow the time range or use the paginated activity endpoint when you need to retrieve further calls.

curl --get "https://koldan.dixilang.com/api/v1/mcp/audit/export" \
  -H "Authorization: Bearer $JWT" \
  --data-urlencode "format=json" \
  --data-urlencode "size=1000" \
  --output mcp-activity.json

curl --get "https://koldan.dixilang.com/api/v1/mcp/audit/export" \
  -H "Authorization: Bearer $JWT" \
  --data-urlencode "format=csv" \
  --data-urlencode "from=2026-09-01T00:00:00Z" \
  --data-urlencode "until=2026-10-01T00:00:00Z" \
  --output mcp-activity.csv

Response

Both formats use Content-Disposition: attachment. Empty JSON exports contain []; empty CSV exports contain only the header row.

See Common Errors for authentication and rate-limit responses.

Common Errors

These responses apply to all endpoints on this page.