MCP Integration

The Keeptrusts Agent SDK consumes MCP (Model Context Protocol) tools through the gateway. The gateway owns MCP transport, policy enforcement, and tool mediation — the SDK configures and consumes, never owns.

The MCP boundary rule

┌─────────────────────────┐
│     Agent Runtime       │  ← consumes MCP results
│     (Agent SDK)         │  ← configures MCP requests
└────────────┬────────────┘
             │ chat request with tool calls
             ▼
┌─────────────────────────┐
│   Keeptrusts Gateway    │  ← OWNS MCP transport
│                         │  ← OWNS policy on tool calls
│   • MCP bridge          │  ← OWNS outbound mediation
│   • Tool policy chain   │
│   • Provider routing    │
└────────────┬────────────┘
             │ mediated tool call
             ▼
┌─────────────────────────┐
│   MCP Server / Tool     │
│   (Knowledge base,      │
│    database, API, etc.)  │
└─────────────────────────┘

The SDK does not:

• Start or own an MCP server
• Bypass gateway policy on tool calls
• Create direct connections to tool backends

The SDK does:

• Send chat requests that may trigger tool use
• Receive tool results mediated by the gateway
• Apply agent identity to tool-using requests
• Read decision events for tool-using interactions

Using MCP tools

When a gateway has MCP providers configured (provider: mcp with a base_url), tool calls happen transparently:

const result = await agent.chat({
  model: "gpt-5.4-mini",
  messages: [
    { role: "user", content: "Search our knowledge base for GDPR data retention policies." },
  ],
});

// The model may have used MCP tools — the response includes the result
console.log(result.choices[0]?.message?.content);

// The decision event records tool usage
const events = await agent.listEvents({ requestId: result.requestId });
console.log(events[0]?.tools_used); // ["knowledge_search"]

Configuring MCP at the gateway

MCP is configured in the gateway policy config, not in the SDK. The gateway admin configures available tools:

# policy-config.yaml (gateway configuration)
providers:
  - name: knowledge-base
    provider: mcp
    base_url: http://localhost:9000/mcp
    description: "Organization knowledge base"
    tools:
      - knowledge_search
      - document_retrieve

The Agent SDK inherits whatever MCP tools the linked gateway exposes.

Agent identity on tool calls

When an agent makes a request that triggers an MCP tool call, the gateway preserves the agent identity through the tool mediation:

• x-keeptrusts-agent-id is forwarded to the MCP server
• The decision event records which agent triggered the tool
• Tool results are policy-checked before returning to the agent

Governance on tool calls

MCP tool calls pass through the same policy chain as regular inference:

Policy phase	Applied to tool calls?
Input firewall	✓ — tool call parameters are checked
Content redaction	✓ — sensitive data is redacted before tool execution
Output filtering	✓ — tool results are filtered before returning
Cost attribution	✓ — tool call costs are attributed to the agent
Audit trail	✓ — tool interactions are recorded

Listing available tools

Query what MCP tools are available through the linked gateway:

const gateways = await agent.listGateways();
for (const gw of gateways) {
  console.log(`Gateway: ${gw.name}`);
  console.log(`MCP tools: ${gw.mcp_tools?.join(", ") ?? "none"}`);
}

Tool results in events

Decision events include tool usage metadata:

const events = await agent.listEvents({ requestId: result.requestId });
const event = events[0];

if (event.tools_used && event.tools_used.length > 0) {
  console.log("Tools used in this request:");
  for (const tool of event.tools_used) {
    console.log(`  - ${tool}`);
  }
}

Multi-turn tool conversations

For multi-turn conversations where the model calls tools iteratively:

const messages = [
  { role: "user", content: "Find our GDPR retention policy, then summarize the key dates." },
];

// The gateway handles the full tool loop:
// 1. Model decides to call knowledge_search
// 2. Gateway mediates the MCP call
// 3. Result returned to model
// 4. Model synthesizes the answer
const result = await agent.chat({
  model: "gpt-5.4-mini",
  messages,
});

// A single decision event covers the full tool loop
const events = await agent.listEvents({ requestId: result.requestId });
console.log(events[0]?.tools_used); // ["knowledge_search"]

Knowledge Base integration

When a Keeptrusts Knowledge Base is bound to the gateway, agents can query it through MCP:

const result = await agent.chat({
  model: "gpt-5.4-mini",
  messages: [
    { role: "user", content: "What does our security policy say about password rotation?" },
  ],
});

// Knowledge base citations are attached to the response
if (result.citations) {
  for (const citation of result.citations) {
    console.log(`Source: ${citation.asset_name} (${citation.version})`);
    console.log(`Excerpt: ${citation.excerpt}`);
  }
}

What the SDK does NOT do with MCP

The following patterns are not supported by design:

// ❌ The SDK does not start an MCP server
agent.startMcpServer(); // does not exist

// ❌ The SDK does not own MCP transport
agent.connectToMcp("http://tool-server/mcp"); // does not exist

// ❌ The SDK does not bypass gateway mediation
agent.directToolCall("knowledge_search", params); // does not exist

All MCP traffic flows through the gateway. This ensures:

• Every tool call is policy-checked
• Every tool call is cost-attributed
• Every tool call appears in the audit trail
• Tool access is controlled by gateway configuration, not agent code