Skip to main content

MCP Integration

Model Context Protocol (MCP) is an open standard that enables agents to interact with external tools, resources, and prompts in a standardized way.

What is MCP?​

MCP provides a unified interface for:

  • Tools: Actions agents can perform (API calls, calculations, file operations)
  • Resources: Data agents can read (files, databases, APIs)
  • Prompts: Pre-defined prompt templates

Instead of custom integrations for each service, MCP provides a standard protocol that works everywhere.

How MCP Works​

Agent ──MCP Protocol──▶ MCP Server ──Native API──▶ External Service
  1. Agent needs to perform an action
  2. Agent calls MCP tool via standard protocol
  3. MCP server translates to native API
  4. Results returned in standard format

MCP Operations​

Tools​

List and execute tools:

// List available tools
const tools = await client.mcp.listTools();

for (const tool of tools) {
  console.log({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema
  });
}

// Execute a tool
const result = await client.mcp.callTool({
  name: 'calculator',
  arguments: {
    operation: 'add',
    a: 10,
    b: 20
  }
});

console.log(result); // { result: 30 }

Resources​

Read external resources:

// List available resources
const resources = await client.mcp.listResources();

// Read a resource
const content = await client.mcp.readResource({
  uri: 'file:///documents/report.md'
});

console.log(content.text);

Prompts​

Use prompt templates:

// List available prompts
const prompts = await client.mcp.listPrompts();

// Get a prompt with arguments
const prompt = await client.mcp.getPrompt({
  name: 'code-review',
  arguments: {
    language: 'typescript',
    focus: 'security'
  }
});

console.log(prompt.messages);

Built-in MCP Tools​

Deeployd includes several built-in MCP tools:

Calculator​

{
  name: 'calculator',
  description: 'Perform mathematical calculations',
  inputSchema: {
    type: 'object',
    properties: {
      operation: { enum: ['add', 'subtract', 'multiply', 'divide', 'power', 'sqrt'] },
      a: { type: 'number' },
      b: { type: 'number' }
    },
    required: ['operation', 'a']
  }
}

Current Time​

{
  name: 'current_time',
  description: 'Get current date and time',
  inputSchema: {
    type: 'object',
    properties: {
      timezone: { type: 'string', default: 'UTC' },
      format: { type: 'string', default: 'ISO' }
    }
  }
}

HTTP Request​

{
  name: 'http_request',
  description: 'Make HTTP requests',
  inputSchema: {
    type: 'object',
    properties: {
      method: { enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] },
      url: { type: 'string' },
      headers: { type: 'object' },
      body: { type: 'string' }
    },
    required: ['method', 'url']
  }
}

Memory​

{
  name: 'memory',
  description: 'Store and retrieve persistent data',
  inputSchema: {
    type: 'object',
    properties: {
      operation: { enum: ['get', 'set', 'delete', 'list'] },
      key: { type: 'string' },
      value: { type: 'any' },
      scope: { enum: ['conversation', 'user', 'agent'] }
    },
    required: ['operation']
  }
}

Random​

{
  name: 'random',
  description: 'Generate random values',
  inputSchema: {
    type: 'object',
    properties: {
      type: { enum: ['number', 'uuid', 'choice'] },
      min: { type: 'number' },
      max: { type: 'number' },
      choices: { type: 'array' }
    },
    required: ['type']
  }
}

JSON​

{
  name: 'json',
  description: 'Parse and manipulate JSON',
  inputSchema: {
    type: 'object',
    properties: {
      operation: { enum: ['parse', 'stringify', 'query', 'transform'] },
      data: { type: 'any' },
      query: { type: 'string' }
    },
    required: ['operation', 'data']
  }
}

Adding MCP Servers​

From npm Package​

await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'npm',
  package: '@anthropic/mcp-server-filesystem',
  config: {
    allowedPaths: ['/documents', '/data']
  }
});

From GitHub​

await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'github',
  repository: 'anthropics/mcp-server-github',
  config: {
    token: process.env.GITHUB_TOKEN
  }
});

From URL​

await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'url',
  url: 'https://mcp.example.com/server.js',
  config: {
    apiKey: process.env.API_KEY
  }
});

Google Workspace​

// taylorwilsdon/google_workspace_mcp
await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'github',
  repository: 'taylorwilsdon/google_workspace_mcp',
  tools: [
    'gmail_search',
    'gmail_send',
    'drive_list',
    'drive_read',
    'calendar_list',
    'calendar_create',
    'docs_read',
    'sheets_read'
  ]
});

Microsoft 365​

// Softeria/ms-365-mcp-server
await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'github',
  repository: 'Softeria/ms-365-mcp-server',
  tools: [
    'outlook_search',
    'outlook_send',
    'onedrive_list',
    'onedrive_read',
    'excel_read',
    'excel_write',
    'teams_send'
  ]
});

Filesystem​

// @anthropic/mcp-server-filesystem
await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'npm',
  package: '@anthropic/mcp-server-filesystem',
  config: {
    allowedPaths: ['/app/data', '/app/reports']
  }
});

Database​

// @anthropic/mcp-server-postgres
await client.integrations.installMcpServer({
  agentId: 'agent-123',
  source: 'npm',
  package: '@anthropic/mcp-server-postgres',
  config: {
    connectionString: process.env.DATABASE_URL,
    readOnly: true
  }
});

Creating Custom MCP Tools​

Define Tool Schema​

const customTool = await client.tools.create({
  name: 'crm_lookup',
  description: 'Look up customer information in CRM',
  category: 'api',
  inputSchema: {
    type: 'object',
    properties: {
      customerId: {
        type: 'string',
        description: 'Customer ID to look up'
      },
      fields: {
        type: 'array',
        items: { type: 'string' },
        description: 'Fields to return'
      }
    },
    required: ['customerId']
  },
  executionType: 'http',
  executionConfig: {
    url: 'https://api.crm.example.com/customers/${customerId}',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ${secrets.CRM_API_KEY}'
    }
  },
  secretsRequired: ['CRM_API_KEY']
});

JavaScript Execution​

const jsTool = await client.tools.create({
  name: 'data_transformer',
  description: 'Transform data using custom logic',
  category: 'javascript',
  inputSchema: {
    type: 'object',
    properties: {
      data: { type: 'array' },
      operation: { enum: ['sum', 'average', 'filter', 'map'] }
    },
    required: ['data', 'operation']
  },
  executionType: 'javascript',
  executionConfig: {
    code: `
      const { data, operation } = input;

      switch (operation) {
        case 'sum':
          return { result: data.reduce((a, b) => a + b, 0) };
        case 'average':
          return { result: data.reduce((a, b) => a + b, 0) / data.length };
        case 'filter':
          return { result: data.filter(Boolean) };
        case 'map':
          return { result: data.map(x => x * 2) };
      }
    `
  }
});

Webhook Execution​

const webhookTool = await client.tools.create({
  name: 'notify_team',
  description: 'Send notification to team',
  category: 'webhook',
  inputSchema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
      channel: { type: 'string' },
      priority: { enum: ['low', 'normal', 'high'] }
    },
    required: ['message']
  },
  executionType: 'webhook',
  executionConfig: {
    url: 'https://hooks.slack.com/services/xxx/yyy/zzz',
    method: 'POST',
    bodyTemplate: {
      text: '${message}',
      channel: '${channel}',
      username: 'Deeployd Agent'
    }
  }
});

Assigning Tools to Agents​

Via API​

await client.agents.update('agent-123', {
  tools: [
    { name: 'calculator' },
    { name: 'http_request' },
    { name: 'memory' },
    { name: 'crm_lookup' }
  ]
});

Via Dashboard​

  1. Go to Agents → Select agent → Tools
  2. Browse available tools
  3. Toggle tools on/off
  4. Configure tool-specific settings
  5. Save changes

MCP Server Management​

List Installed Servers​

const servers = await client.mcp.listServers({
  agentId: 'agent-123'
});

Update Server Config​

await client.mcp.updateServer({
  agentId: 'agent-123',
  serverId: 'server-456',
  config: {
    newSetting: 'value'
  }
});

Remove Server​

await client.mcp.removeServer({
  agentId: 'agent-123',
  serverId: 'server-456'
});

MCP Protocol Details​

Initialization Handshake​

// Client sends initialize
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    },
    "clientInfo": {
      "name": "deeployd",
      "version": "1.0.0"
    }
  },
  "id": 1
}

// Server responds
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": { "listChanged": true }
    },
    "serverInfo": {
      "name": "example-server",
      "version": "1.0.0"
    }
  },
  "id": 1
}

Tool Call​

// Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {
      "operation": "add",
      "a": 10,
      "b": 20
    }
  },
  "id": 2
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "30"
      }
    ]
  },
  "id": 2
}

Best Practices​

1. Use Appropriate Tools​

// ✅ Good - specific tool for the job
tools: ['crm_lookup', 'email_send', 'calendar_check']

// ❌ Bad - overly broad access
tools: ['http_request'] // Can access anything

2. Limit Tool Scope​

// Restrict filesystem access
config: {
  allowedPaths: ['/app/data'], // Only this directory
  readOnly: true // No writes
}

3. Secure Secrets​

// Use secrets, not hardcoded values
secretsRequired: ['API_KEY', 'DATABASE_URL']

// Secrets are encrypted at rest and injected at runtime

4. Validate Inputs​

inputSchema: {
  type: 'object',
  properties: {
    email: {
      type: 'string',
      format: 'email' // Validation
    },
    amount: {
      type: 'number',
      minimum: 0,
      maximum: 10000 // Bounds
    }
  },
  required: ['email', 'amount']
}

5. Handle Errors​

try {
  const result = await client.mcp.callTool({
    name: 'external_api',
    arguments: { ... }
  });
} catch (error) {
  if (error.code === 'TOOL_EXECUTION_ERROR') {
    // Handle gracefully
  }
}

Next: Explore Integrations for pre-built connections to popular services.