AI Agent & MCP Bridge

The AI Agent Bridge exposes the Public Data API as a tool catalog that AI agents can discover and call. It is intentionally thin: all authentication, scopes, rate limiting, and audit logging still run through the existing Public Data API.

Why this exists

Production clients using total-integration are increasingly automating work through AI agents. Instead of building a custom MCP server that duplicates the Public Data API, Total Access adds:

• GET /api/v1/public/data/tools — discover actions as tool schemas.
• POST /api/v1/public/mcp — a stateless MCP-compatible JSON-RPC endpoint.

Agents can continue to call POST /api/v1/public/data directly, or use the MCP adapter for better compatibility with Claude, Cursor, and other MCP-native clients.

Authentication

Same as the Public Data API: include an API key in the X-API-Key header.

X-API-Key: ta_sk_...

The API key must have the scope required by each tool. For example, get-employees requires employees:read. Write actions require specific scopes: send-thread-message requires threads:send_message, create-work-item requires work_items:write, create-appointment requires appointments:write, and create-comment requires comments:write.

Endpoints

Tool discovery

MCP format

curl -G https://totalaccess.co.za/api/v1/public/data/tools \
  -H "X-API-Key: ta_sk_..." \
  -d "format=mcp"

Example response:

{
  "success": true,
  "format": "mcp",
  "tools": [
    {
      "name": "get-employees",
      "description": "Get employees for the client (requires scope: employees:read)",
      "inputSchema": {
        "type": "object",
        "properties": {
          "department": { "type": "string", "description": "Filter by department" },
          "is_active": { "type": "string", "description": "Filter by active status (default: true)" },
          "limit": { "type": "string", "description": "Results per page (max 500, default 100)" },
          "offset": { "type": "string", "description": "Pagination offset (default 0)" }
        },
        "required": [],
        "additionalProperties": false
      }
    }
  ]
}

OpenAI / Anthropic function format

curl -G https://totalaccess.co.za/api/v1/public/data/tools \
  -H "X-API-Key: ta_sk_..." \
  -d "format=openai"

The response replaces inputSchema with parameters so it can be dropped directly into an OpenAI tools or Anthropic tools array.

Calling tools through the MCP adapter

The MCP adapter speaks stateless JSON-RPC. Each tools/call is translated into a POST /api/v1/public/data call, so the same API-key auth, scopes, rate limits, and api_usage audit log apply.

initialize

curl -X POST https://totalaccess.co.za/api/v1/public/mcp \
  -H "X-API-Key: ta_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

tools/list

curl -X POST https://totalaccess.co.za/api/v1/public/mcp \
  -H "X-API-Key: ta_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

tools/call

curl -X POST https://totalaccess.co.za/api/v1/public/mcp \
  -H "X-API-Key: ta_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get-employees",
      "arguments": {
        "is_active": "true",
        "limit": "10"
      }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\":true,\"data\":[...]}"
      }
    ],
    "isError": false
  }
}

If the underlying Public Data API call returns an error or a success: false payload, isError is set to true and the full response is included as text.

Calling actions directly

Agents that do not speak MCP can still call POST /api/v1/public/data directly:

curl -X POST https://totalaccess.co.za/api/v1/public/data \
  -H "X-API-Key: ta_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "get-employees",
    "is_active": true,
    "limit": 10
  }'

Rate limiting

The MCP adapter shares the Public Data API rate limit of 100 requests per minute per API key. Rate limit headers are set by the underlying POST /api/v1/public/data call and propagated back in the tools/call response where the transport allows.

Security best practices

• Create a dedicated API key per agent or integration.
• Grant only the scopes the agent actually needs. Avoid * unless absolutely necessary.
• Restrict the API key to the agent's outbound IP addresses if it calls from a fixed host.
• Set an expiry date on keys that are temporary or rotated. Expired keys are rejected at authentication.
• Monitor api_usage logs for unexpected tool usage.
• Do not expose mcp or public/data endpoints without HTTPS in production.
• Write actions (create-work-item, create-appointment, create-comment, send-thread-message, create-recurring-job, generate-recurring-job) require dedicated write scopes. Grant these only to agents that need to create data, not to read-only agents. Use the recurring:write scope for recurring job management actions.

Claude Desktop / Cursor configuration

For clients that support HTTP-based MCP (or a local stdio proxy), point the transport at:

{
  "mcpServers": {
    "totalaccess": {
      "url": "https://totalaccess.co.za/api/v1/public/mcp",
      "headers": {
        "X-API-Key": "ta_sk_..."
      }
    }
  }
}

If the client only supports stdio, a one-line stdio-to-HTTP proxy (for example, a small Node script) can forward MCP messages to https://totalaccess.co.za/api/v1/public/mcp with the X-API-Key header injected.

Tool catalog source of truth

The GET /api/v1/public/data/tools catalog is generated from the same available_actions metadata returned by GET /api/v1/public/data. When new actions are added to the Public Data API, they automatically appear in the tool catalog and the MCP adapter without additional code.