Agent MCP Overview

Agent MCP (Model Context Protocol) is TraceMem's interface for AI agents. It provides a standardized way for agents to interact with TraceMem's decision tracking and data governance platform.

What is Agent MCP?

Agent MCP is a JSON-RPC 2.0 server that provides tools for:

• Creating and managing decision envelopes
• Reading data through governed data products
• Evaluating policies for compliance
• Requesting human approvals when needed
• Writing data with full audit trails
• Generating cryptographic proof of decisions

All operations are automatically traced, creating an immutable audit log of agent behavior.

Protocol Details

JSON-RPC 2.0

Agent MCP uses JSON-RPC 2.0 over HTTP:

Request Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "decision_create",
    "arguments": {
      "intent": "customer.order.create",
      "automation_mode": "propose"
    }
  }
}

Response Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"decision_id\": \"TMEM_...\", \"status\": \"open\"}"
      }
    ]
  }
}

Connection

Endpoint: https://mcp.tracemem.com

Headers:

Authorization: Agent <your-api-key>
Content-Type: application/json

Method: POST

Initialization

Before using tools, initialize the MCP session:

response = requests.post('https://mcp.tracemem.com',
    headers={'Authorization': 'Agent YOUR_API_KEY'},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
            "protocolVersion": "2024-11-05",
            "capabilities": {},
            "clientInfo": {"name": "my-agent", "version": "1.0.0"}
        }
    })

Authentication

All requests require an Agent API key in the Authorization header:

Authorization: Agent <api-key>

API keys are:

• Tenant-scoped
• Grant access to specific data products (read/write permissions)
• Provide policy evaluation capabilities
• Enable approval request channels

Get your API key:

1. Navigate to Settings → Agents in the dashboard
2. Create an agent (if you haven't already)
3. Create a credential to get an API key
4. Save the API key securely (it's only shown once)

Available Tools

Decision Lifecycle

• decision_create - Create a new decision envelope
• decision_get - Get decision status
• decision_close - Close a decision (commit or rollback)
• decision_trace - Get complete trace (self-access only)
• decision_receipt - Get cryptographic receipt

Data Access

• decision_read - Read data through a Data Product
• decision_write - Write data through a Data Product

Policy Evaluation

• decision_evaluate - Evaluate a policy

Approval Workflow

• decision_request_approval - Request human approval

Context Events

• decision_add_context - Add context event to trace

Discovery

• products_list - List available Data Products
• product_get - Get Data Product details
• capabilities_get - Get agent capabilities

Error Handling

All errors follow JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "decision_id is required"
  }
}

Common Error Codes:

• -32600 Invalid Request - Missing required parameters
• -32601 Method not found - Unknown tool name
• -32602 Invalid params - Wrong parameter types
• -32603 Internal error - Server error

HTTP Status Codes:

• 200 OK - Success (even for JSON-RPC errors)
• 401 Unauthorized - Invalid API key
• 403 Forbidden - Permission denied
• 429 Too Many Requests - Rate limited

Rate Limits

• 100 requests/second per API key
• 1000 decisions/hour per agent
• 10 MB maximum request size

Exceeded limits return HTTP 429 with Retry-After header.

Security

API Key Security

• Store API keys securely (environment variables, secrets manager)
• Never commit API keys to source control
• Rotate keys regularly
• Use separate keys for dev/staging/production

Data Access

• Only request data products you need
• Specify minimal queries (filter by ID when possible)
• All access is logged and auditable

Approval Security

• Approvals use cryptographic signatures
• Expired approvals cannot be used
• Approval tokens are single-use