MCP-I Integration

View as Markdown

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 anonymousEvery call is signed by the agent’s DID
No authorization modelIBCT provides scoped authorization per call
No audit trailSigned audit receipts for every action
Trust is implicitDelegation chain verified before tool execution
No agent identityAgent DID + operator DID in every request

Architecture

MCP-I Request Format

Standard MCP tool call with IDA identity headers:

1{
2 "jsonrpc": "2.0",
3 "method": "tool/call",
4 "params": {
5 "name": "create_order",
6 "arguments": {
7 "items": [
8 { "product": "Organic Milk", "quantity": 2 },
9 { "product": "Sourdough Bread", "quantity": 1 }
10 ],
11 "merchant": "FreshMart"
12 }
13 },
14 "id": "req-001",
15
16 "ida": {
17 "agentDid": "did:adi:agent:shop01...",
18 "ibct": "eyJhbGciOiJFZERTQSIsInR5cCI6IklCQ1Qrand0In0...",
19 "delegationChain": [
20 "urn:uuid:root-delegation"
21 ]
22 }
23}

MCP-I Response Format

Standard MCP response with audit receipt:

1{
2 "jsonrpc": "2.0",
3 "result": {
4 "content": [
5 {
6 "type": "text",
7 "text": "Order created: #ORD-12345. Total: $8.47"
8 }
9 ]
10 },
11 "id": "req-001",
12
13 "ida": {
14 "auditReceipt": {
15 "id": "receipt-f47ac10b...",
16 "agentDid": "did:adi:agent:shop01...",
17 "operatorDid": "did:adi:human001...",
18 "tool": "create_order",
19 "timestamp": "2026-03-28T14:23:01Z",
20 "ibctHash": "0x7f3a...",
21 "delegationValid": true,
22 "scopeValid": true,
23 "result": "success",
24 "signature": "z58DAdFfa9SkqZMVPxAQpic7ndTn4..."
25 }
26 }
27}

Setting Up MCP-I Server

Tool Registration with Scope Requirements

1const mcpiServer = new MCPIServer({
2 idaApiUrl: 'http://localhost:8080',
3 serverDid: 'did:adi:service:freshmart...',
4});
5
6mcpiServer.registerTool({
7 name: 'create_order',
8 description: 'Create a new grocery order',
9 requiredScope: ['purchase-groceries'],
10 requiredTrustScore: 60,
11 requiredAutonomyLevel: 'Junior',
12 inputSchema: {
13 type: 'object',
14 properties: {
15 items: { type: 'array' },
16 merchant: { type: 'string' }
17 }
18 },
19 handler: async (params, agentContext) => {
20 // agentContext contains verified agent info
21 console.log(`Agent ${agentContext.agentDid} creating order`);
22 console.log(`Operator: ${agentContext.operatorDid}`);
23 console.log(`Trust score: ${agentContext.trustScore}`);
24
25 return { orderId: 'ORD-12345', total: 8.47 };
26 }
27});

Middleware: Identity Verification

1mcpiServer.use(async (request, next) => {
2 const { agentDid, ibct, delegationChain } = request.ida;
3
4 // 1. Verify IBCT
5 const ibctResult = await idaClient.verifyIBCT(ibct, {
6 expectedAudience: serverDid,
7 expectedAction: {
8 type: 'tool-call',
9 resource: request.params.name
10 }
11 });
12
13 if (!ibctResult.valid) {
14 throw new Error(`IBCT verification failed: ${ibctResult.reason}`);
15 }
16
17 // 2. Check trust score meets tool requirements
18 const tool = mcpiServer.getTool(request.params.name);
19 if (ibctResult.agent.trustScore < tool.requiredTrustScore) {
20 throw new Error(`Trust score ${ibctResult.agent.trustScore} below required ${tool.requiredTrustScore}`);
21 }
22
23 // 3. Verify scope covers this tool
24 if (!ibctResult.effectiveScope.includes(tool.requiredScope)) {
25 throw new Error('Agent scope does not cover this tool');
26 }
27
28 // Attach verified context
29 request.agentContext = ibctResult;
30 return next(request);
31});

Audit Receipts

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

1{
2 "id": "receipt-f47ac10b-58cc-4372-a567-0e02b2c3d479",
3 "agentDid": "did:adi:agent:shop01...",
4 "operatorDid": "did:adi:human001...",
5 "serverDid": "did:adi:service:freshmart...",
6 "tool": "create_order",
7 "arguments": { "items": ["..."], "merchant": "FreshMart" },
8 "result": "success",
9 "timestamp": "2026-03-28T14:23:01Z",
10 "ibctHash": "sha256:7f3a9b2e1c4d...",
11 "delegationChain": ["did:adi:human001...", "did:adi:agent:shop01..."],
12 "proof": {
13 "type": "Ed25519Signature2020",
14 "verificationMethod": "did:adi:service:freshmart...#key-1",
15 "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndTn4..."
16 }
17}

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:

1mcpiServer.registerTool({
2 name: 'process_payment',
3 requiredScope: ['payment'],
4 hitlRequired: true, // Requires human approval
5 hitlThreshold: 100, // HITL for amounts > $100
6 handler: async (params, agentContext) => {
7 if (params.amount > 100) {
8 // Block until human approves via wallet notification
9 const approval = await idaClient.requestHITL({
10 operatorDid: agentContext.operatorDid,
11 agentDid: agentContext.agentDid,
12 action: `Pay $${params.amount} to ${params.merchant}`,
13 timeout: 300 // 5 minutes
14 });
15
16 if (!approval.approved) {
17 throw new Error('Human approval denied');
18 }
19 }
20
21 return processPayment(params);
22 }
23});

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
$npm install @ida/mcp-i
1import { createMCPIMiddleware } from '@ida/mcp-i';
2
3const mcpServer = existingMCPServer;
4mcpServer.use(createMCPIMiddleware({
5 idaApiUrl: 'http://localhost:8080',
6 serverDid: 'did:adi:service:myservice...',
7 auditEnabled: true
8}));