MCP Adapters

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. ContractSpec provides MCP adapters that allow you to expose your capabilities as MCP tools and consume external MCP servers as capabilities.

Why MCP integration matters

AI agents need access to real-world tools and data to be useful. MCP provides a standardized way to expose these capabilities. By integrating ContractSpec with MCP, you can:

• Let AI agents invoke your ContractSpec capabilities safely and securely
• Use external MCP servers (databases, APIs, search engines) as capability providers in your workflows
• Build AI-powered features without writing custom integration code
• Enforce policies on AI agent actions just like any other user

Exposing capabilities as MCP tools

Any CapabilitySpec can be automatically exposed as an MCP tool. ContractSpec generates:

• A tool schema describing the capability's inputs, outputs, and purpose
• An MCP server endpoint that AI agents can connect to
• Policy enforcement ensuring agents can only invoke capabilities they're authorized to use
• Audit logging of all agent actions for compliance and debugging

Example: Exposing a capability

Here's how to expose ContractSpec operations as MCP tools:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { createMcpServer } from '@lssm/lib.contracts/server/provider-mcp';
import { registry, resources, prompts } from './lib/registry';

const server = new McpServer({
  name: 'my-app-mcp',
  version: '1.0.0',
});

createMcpServer(server, registry, resources, prompts, {
  toolCtx: () => ({ actor: 'ai-agent' }),
  promptCtx: () => ({ userId: null, orgId: null }),
  resourceCtx: () => ({ userId: null, orgId: null }),
});

const transport = new StdioServerTransport();
await server.connect(transport);

AI agents can now discover and invoke your operations through the MCP protocol. ContractSpec handles authentication, authorization, and execution automatically via the `SpecRegistry`.

Consuming external MCP servers

You can integrate external MCP servers into your workflows. Define an integration spec and use it in your operations:

import { defineIntegration } from '@lssm/lib.contracts';
import { SchemaModel, ScalarTypeEnum } from '@lssm/lib.schema';

const SearchProductsIntegration = defineIntegration({
  meta: {
    name: 'products.search',
    version: 1,
    category: 'mcp',
    description: 'Search products via external MCP server',
  },
  connection: {
    serverUrl: 'https://api.example.com/mcp',
    toolName: 'search_products',
  },
  io: {
    input: new SchemaModel({
      name: 'SearchProductsInput',
      fields: {
        query: { type: ScalarTypeEnum.String(), isOptional: false },
        category: { type: ScalarTypeEnum.String(), isOptional: true },
      },
    }),
    output: new SchemaModel({
      name: 'ProductResults',
      fields: {
        products: { type: ScalarTypeEnum.JSON(), isOptional: false, isArray: true },
      },
    }),
  },
});

Policy enforcement for AI agents

AI agents are treated like any other actor in ContractSpec. They must authenticate, and all their actions are subject to PolicySpecs. You can define specific policies in TypeScript:

import { definePolicy } from '@lssm/lib.contracts';

export const AIAgentRestrictions = definePolicy({
  meta: {
    name: 'ai.agent.restrictions',
    version: 1,
    description: 'Restrict AI agent actions',
  },
  rules: [
    {
      id: 'agents-read-only',
      effect: 'DENY',
      condition: (ctx) => ctx.actor === 'ai-agent' && ctx.action === 'write',
    },
    {
      id: 'agents-require-approval',
      effect: 'DENY',
      condition: (ctx, spec) => 
        ctx.actor === 'ai-agent' && 
        spec.policy.escalate === 'human_review' &&
        !ctx.approvalGranted,
    },
  ],
});

Human-in-the-loop workflows

For sensitive operations, you can require human approval before an AI agent can proceed. ContractSpec provides built-in approval workflows:

• Agent requests permission to invoke a capability
• Request is sent to designated approvers (via email, Slack, etc.)
• Approver reviews the request and approves or denies it
• Agent receives the decision and can proceed if approved

All approval decisions are logged in the audit log.

Best practices

• Start with read-only capabilities for AI agents—only grant write access when necessary.
• Use human-in-the-loop approval for any capability that modifies critical data or triggers financial transactions.
• Set rate limits to prevent runaway agents from overwhelming your system.
• Provide clear, detailed descriptions for each capability so agents know when to use them.
• Monitor agent actions closely in production and adjust policies as needed.
• Test agent integrations thoroughly with realistic scenarios before deploying.