> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# MCP-I Integration

IDA extends the Model Context Protocol (MCP) with cryptographically verifiable identity and delegation -- called **MCP-I** (MCP with Identity). This ensures that every tool call made by an AI agent through MCP carries provenance and authorization proof.

## What is MCP?

The Model Context Protocol (MCP) is a standard protocol for connecting AI models to external tools and data sources. It defines how an AI model can:

* Discover available tools
* Invoke tools with parameters
* Receive structured results

## What MCP-I Adds

| MCP (Standard)           | MCP-I (IDA Extension)                           |
| ------------------------ | ----------------------------------------------- |
| Tool calls are anonymous | Every call is signed by the agent's DID         |
| No authorization model   | IBCT provides scoped authorization per call     |
| No audit trail           | Signed audit receipts for every action          |
| Trust is implicit        | Delegation chain verified before tool execution |
| No agent identity        | Agent DID + operator DID in every request       |

## Architecture

```mermaid
sequenceDiagram
    participant Agent
    participant MCP-I Server
    participant IDA Verifier
    participant Tool

    Agent->>MCP-I Server: tool/call + IBCT
    MCP-I Server->>IDA Verifier: Verify IBCT
    IDA Verifier->>IDA Verifier: Check agent DID
    IDA Verifier->>IDA Verifier: Verify delegation chain
    IDA Verifier->>IDA Verifier: Validate scope covers tool
    IDA Verifier->>MCP-I Server: Verification result
    MCP-I Server->>Tool: Execute tool call
    Tool->>MCP-I Server: Tool result
    MCP-I Server->>MCP-I Server: Create signed audit receipt
    MCP-I Server->>Agent: Result + audit receipt
```

## MCP-I Request Format

Standard MCP tool call with IDA identity headers:

```json
{
  "jsonrpc": "2.0",
  "method": "tool/call",
  "params": {
    "name": "create_order",
    "arguments": {
      "items": [
        { "product": "Organic Milk", "quantity": 2 },
        { "product": "Sourdough Bread", "quantity": 1 }
      ],
      "merchant": "FreshMart"
    }
  },
  "id": "req-001",

  "ida": {
    "agentDid": "did:adi:agent:shop01...",
    "ibct": "eyJhbGciOiJFZERTQSIsInR5cCI6IklCQ1Qrand0In0...",
    "delegationChain": [
      "urn:uuid:root-delegation"
    ]
  }
}
```

## MCP-I Response Format

Standard MCP response with audit receipt:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Order created: #ORD-12345. Total: $8.47"
      }
    ]
  },
  "id": "req-001",

  "ida": {
    "auditReceipt": {
      "id": "receipt-f47ac10b...",
      "agentDid": "did:adi:agent:shop01...",
      "operatorDid": "did:adi:human001...",
      "tool": "create_order",
      "timestamp": "2026-03-28T14:23:01Z",
      "ibctHash": "0x7f3a...",
      "delegationValid": true,
      "scopeValid": true,
      "result": "success",
      "signature": "z58DAdFfa9SkqZMVPxAQpic7ndTn4..."
    }
  }
}
```

## Setting Up MCP-I Server

### Tool Registration with Scope Requirements

```javascript
const mcpiServer = new MCPIServer({
  idaApiUrl: 'http://localhost:8080',
  serverDid: 'did:adi:service:freshmart...',
});

mcpiServer.registerTool({
  name: 'create_order',
  description: 'Create a new grocery order',
  requiredScope: ['purchase-groceries'],
  requiredTrustScore: 60,
  requiredAutonomyLevel: 'Junior',
  inputSchema: {
    type: 'object',
    properties: {
      items: { type: 'array' },
      merchant: { type: 'string' }
    }
  },
  handler: async (params, agentContext) => {
    // agentContext contains verified agent info
    console.log(`Agent ${agentContext.agentDid} creating order`);
    console.log(`Operator: ${agentContext.operatorDid}`);
    console.log(`Trust score: ${agentContext.trustScore}`);

    return { orderId: 'ORD-12345', total: 8.47 };
  }
});
```

### Middleware: Identity Verification

```javascript
mcpiServer.use(async (request, next) => {
  const { agentDid, ibct, delegationChain } = request.ida;

  // 1. Verify IBCT
  const ibctResult = await idaClient.verifyIBCT(ibct, {
    expectedAudience: serverDid,
    expectedAction: {
      type: 'tool-call',
      resource: request.params.name
    }
  });

  if (!ibctResult.valid) {
    throw new Error(`IBCT verification failed: ${ibctResult.reason}`);
  }

  // 2. Check trust score meets tool requirements
  const tool = mcpiServer.getTool(request.params.name);
  if (ibctResult.agent.trustScore < tool.requiredTrustScore) {
    throw new Error(`Trust score ${ibctResult.agent.trustScore} below required ${tool.requiredTrustScore}`);
  }

  // 3. Verify scope covers this tool
  if (!ibctResult.effectiveScope.includes(tool.requiredScope)) {
    throw new Error('Agent scope does not cover this tool');
  }

  // Attach verified context
  request.agentContext = ibctResult;
  return next(request);
});
```

## Audit Receipts

Every MCP-I tool call generates a signed audit receipt:

```json
{
  "id": "receipt-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "agentDid": "did:adi:agent:shop01...",
  "operatorDid": "did:adi:human001...",
  "serverDid": "did:adi:service:freshmart...",
  "tool": "create_order",
  "arguments": { "items": ["..."], "merchant": "FreshMart" },
  "result": "success",
  "timestamp": "2026-03-28T14:23:01Z",
  "ibctHash": "sha256:7f3a9b2e1c4d...",
  "delegationChain": ["did:adi:human001...", "did:adi:agent:shop01..."],
  "proof": {
    "type": "Ed25519Signature2020",
    "verificationMethod": "did:adi:service:freshmart...#key-1",
    "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndTn4..."
  }
}
```

Audit receipts are:

* Signed by the MCP-I server's DID key
* Stored on-chain (hash) and off-chain (full receipt)
* Queryable via the Agent Audit Trail API
* Used as input signals for trust score computation

## Human-in-the-Loop (HITL)

For high-risk tool calls, MCP-I can require real-time human approval:

```javascript
mcpiServer.registerTool({
  name: 'process_payment',
  requiredScope: ['payment'],
  hitlRequired: true,  // Requires human approval
  hitlThreshold: 100,  // HITL for amounts > $100
  handler: async (params, agentContext) => {
    if (params.amount > 100) {
      // Block until human approves via wallet notification
      const approval = await idaClient.requestHITL({
        operatorDid: agentContext.operatorDid,
        agentDid: agentContext.agentDid,
        action: `Pay $${params.amount} to ${params.merchant}`,
        timeout: 300 // 5 minutes
      });

      if (!approval.approved) {
        throw new Error('Human approval denied');
      }
    }

    return processPayment(params);
  }
});
```

## Migration from Standard MCP

To add IDA identity to an existing MCP server:

1. Install the `@ida/mcp-i` middleware package
2. Register the server's DID on the ADI blockchain
3. Add `ida` namespace to MCP request/response handlers
4. Configure required scopes for each tool
5. Enable audit receipt generation

```bash
npm install @ida/mcp-i
```

```javascript
import { createMCPIMiddleware } from '@ida/mcp-i';

const mcpServer = existingMCPServer;
mcpServer.use(createMCPIMiddleware({
  idaApiUrl: 'http://localhost:8080',
  serverDid: 'did:adi:service:myservice...',
  auditEnabled: true
}));
```