API Structure

Manager/Admin creates company/coach grant
-> Backend validates modules, write tools, consent, and expiry
-> Backend stores CompanyMcpGrant with apiKeyHash
-> Backend returns plaintext apiKey once
-> MCP client uses Authorization: Bearer <apiKey>

AI client registers OAuth client
-> AI client starts authorization request
-> Coach is redirected to consent screen
-> Coach approves modules/write tools/consent
-> Backend creates CompanyMcpGrant and authorization code
-> AI client exchanges code for access and refresh tokens

AI client registers OAuth client
-> AI client starts authorization request
-> Client is redirected to client consent screen
-> Backend checks the company MCP feature, client-company relationship, client AI access, and company client MCP policy
-> If any gate is disabled, no grant or authorization code is created
-> Client approves only explicit client_ai_* modules, write tools, and consent
-> Backend creates CompanyMcpGrant with subjectType=client and subjectClientId
-> Backend creates authorization code
-> AI client exchanges code for access and refresh tokens

MCP client calls POST /mcp/v1
-> Persistent pre-parse IP and parsed IP/bearer-key rate limits are consumed
-> Official @modelcontextprotocol/server v2 transport validates Host and Origin
-> Backend resolves API key or OAuth access token
-> Backend checks grant status, expiry, and company status
-> Backend checks the company MCP feature for every grant
-> Backend checks company/coach owner role or client AI access, policy, and subject binding
-> Backend filters requested tool by subject type, allowedModules, consent, and allowedWriteTools
-> Persistent per-grant query budget and per-company/tool circuit state are checked
-> Write calls require params._meta.idempotencyKey and claim durable replay state
-> Tool executes
-> Write replay result and generic audit metadata are durably persisted
-> A post-mutation replay persistence failure leaves the key processing and returns an error
-> JSON-RPC result is returned

Manager/Admin rotates API-key grant
-> Backend generates new apiKey
-> Backend replaces stored apiKeyHash
-> Old API key stops working
-> New plaintext apiKey is returned once

Manager/Admin revokes company/coach grant, or client revokes own client grant
-> Grant status becomes revoked
-> Static API key stops working if present
-> OAuth tokens linked to the grant are revoked
-> Audit history remains available

Manager/Admin opens audit list, detail, metrics, or CSV export
-> Backend applies filters like date range, tool, module, status, error, IP, and grant
-> Backend returns company-scoped records only
-> Argument values remain hidden
-> Argument key names and execution metadata are visible

Manager/Admin opens one grant
-> Backend loads grant lifecycle events, tool-call audit logs, and anomalies
-> Backend merges them into a reverse-chronological activity timeline
-> UI can show created, updated, rotated, revoked, calls, failures, and anomalies together

Backend records anomaly
-> Dashboard shows open anomaly
-> Manager/Admin reviews event
-> Anomaly status is updated to reviewed or dismissed

{
  "status": 200,
  "error": false,
  "message": "MESSAGE_KEY",
  "data": {}
}

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "result": {}
}

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32602,
    "message": "Unknown or unavailable tool: example_tool"
  }
}

timeframe=day|week|month|year
from=<ISO date or date-time>
to=<ISO date or date-time>
timezone=<IANA timezone>
grantId=<ObjectId>
toolName=<tool name>
moduleName=<module key>
readWrite=read|write
status=success|error
recentLimit=1..25

grantId=<ObjectId>
from=<ISO date or date-time>
to=<ISO date or date-time>
toolName=<tool name>
moduleName=<module key>
readWrite=read|write
status=success|error
errorCode=<error key>
requestIp=<IP address>
page=<page number>
limit=<1..100>