MCP

Connect Twig AI agents to external tools, data sources, and services using the Model Context Protocol.

Overview

The Model Context Protocol (MCP) is an open protocol that standardizes how AI applications connect to external data sources and tools. MCP enables Twig agents to access real-time data, execute actions, and integrate with third-party services beyond their built-in capabilities.

Key Benefits

Extensibility: Add custom tools and data sources without modifying agent code
Standardization: Use a consistent protocol across different integrations
Real-time Data: Access live data from external systems during conversations
Tool Execution: Enable agents to perform actions in external systems
Modular Architecture: Add or remove capabilities dynamically

Architecture

MCP follows a client-server architecture:

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Twig AI   │  MCP    │ MCP Server  │         │  External   │
│   Agent     │◄───────►│  (Host)     │◄───────►│  Services   │
└─────────────┘         └─────────────┘         └─────────────┘
  (MCP Client)           (Protocol)              (Data/Tools)

MCP Client: Twig AI agent that requests data or tools
MCP Server: Host that provides resources and tools to the agent
Resources: Data sources (files, databases, APIs)
Tools: Actions the agent can execute

Getting Started

Prerequisites

Twig AI account with API access
MCP server implementation (or use pre-built servers)
Understanding of Twig REST API

Quick Setup

Choose or Build an MCP Server
- Use pre-built servers for common integrations
- Build custom servers for proprietary systems
Configure Connection
- Register your MCP server endpoint
- Set up authentication credentials
- Define available resources and tools
Enable for Agents
- Assign MCP capabilities to specific agents
- Configure which resources agents can access
- Test the integration

MCP Concepts

Resources

Resources are data sources that agents can query:

Files: Documents, PDFs, spreadsheets
Databases: SQL, NoSQL, vector databases
APIs: REST, GraphQL endpoints
Real-time Streams: Logs, metrics, events

Example Resource:

{
  "uri": "file:///docs/policy.pdf",
  "name": "Company Policy Document",
  "mimeType": "application/pdf",
  "description": "Latest company policies and procedures"
}

Tools

Tools are actions agents can execute:

Data Operations: Search, filter, aggregate
System Actions: Create tickets, send emails
Calculations: Complex computations, data transformations
Integrations: Trigger workflows in external systems

Example Tool:

{
  "name": "create_support_ticket",
  "description": "Create a new support ticket in Zendesk",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "description": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] }
    },
    "required": ["title", "description"]
  }
}

Prompts

Prompts are reusable templates for common agent interactions:

{
  "name": "analyze_customer_data",
  "description": "Analyze customer behavior patterns",
  "arguments": [
    {
      "name": "customer_id",
      "description": "Customer identifier",
      "required": true
    }
  ]
}

Configuration

Connecting an MCP Server

API Endpoint

POST /api/v1/mcp/servers

Request Body

{
  "name": "Zendesk Integration",
  "description": "Access Zendesk tickets and create support tickets",
  "endpoint": "https://mcp.example.com/zendesk",
  "auth": {
    "type": "bearer",
    "token": "YOUR_MCP_SERVER_TOKEN"
  },
  "capabilities": {
    "resources": true,
    "tools": true,
    "prompts": false
  }
}

Response

{
  "serverId": "mcp-server-123",
  "status": "active",
  "connectedAt": "2026-01-26T10:30:00Z",
  "availableResources": 12,
  "availableTools": 5
}

Assigning to Agents

Enable MCP for specific agents:

PUT /api/ai-agent-managers/{agentId}/mcp

{
  "mcpServers": ["mcp-server-123"],
  "allowedResources": [
    "file:///docs/*",
    "db://tickets/*"
  ],
  "allowedTools": [
    "create_support_ticket",
    "search_knowledge_base"
  ]
}

Using MCP Resources

Query Resources

Agents automatically query MCP resources when relevant:

User Question:

"What's our current refund policy?"

Agent Behavior:

Identifies need for policy document
Queries MCP server for file:///docs/refund-policy.pdf
Retrieves content
Generates response using retrieved data

Manual Resource Access

Explicitly request resources via API:

POST /api/mcp/resources/query

{
  "serverId": "mcp-server-123",
  "resourceUri": "file:///docs/refund-policy.pdf",
  "agentId": "agent-123"
}

Using MCP Tools

Automatic Tool Execution

Agents decide when to use tools based on context:

User Request:

"Create a support ticket for billing issue"

Agent Actions:

Identifies need to create ticket
Calls create_support_ticket tool
Receives confirmation
Reports back to user

Tool Execution Flow

{
  "toolName": "create_support_ticket",
  "arguments": {
    "title": "Billing Issue - Invoice #12345",
    "description": "Customer reports incorrect charge on invoice",
    "priority": "high"
  }
}

Response:

{
  "success": true,
  "result": {
    "ticketId": "ZD-9876",
    "ticketUrl": "https://support.example.com/tickets/9876",
    "createdAt": "2026-01-26T10:35:00Z"
  }
}

Pre-built MCP Servers

Available Integrations

Server

Resources

Tools

Status

Zendesk

Tickets, Articles

Create/Update Tickets

Stable

Salesforce

Accounts, Contacts, Cases

Create Records

Beta

GitHub

Repositories, Issues, PRs

Create Issues

Stable

Google Drive

Documents, Sheets

Read Files

Stable

Slack

Messages, Channels

Send Messages

Beta

PostgreSQL

Tables, Views

Query Data

Stable

MongoDB

Collections

Query/Aggregate

Beta

Installing Pre-built Servers

curl -X POST https://api.twig.so/api/v1/mcp/install \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "zendesk",
    "credentials": {
      "subdomain": "your-company",
      "apiToken": "YOUR_ZENDESK_TOKEN",
      "email": "[email protected]"
    }
  }'

Building Custom MCP Servers

Server Implementation

Create a server that implements the MCP protocol:

Required Endpoints:

POST /mcp/initialize - Handshake and capability negotiation
GET /mcp/resources/list - List available resources
POST /mcp/resources/read - Read specific resource
GET /mcp/tools/list - List available tools
POST /mcp/tools/call - Execute a tool

Example: Node.js Server

import express from 'express';
import { MCPServer } from '@modelcontextprotocol/sdk';

const server = new MCPServer({
  name: "Custom CRM Integration",
  version: "1.0.0"
});

// Register resources
server.resource({
  uri: "crm://customers/*",
  name: "Customer Database",
  description: "Access customer records"
}, async (uri) => {
  const customerId = uri.split('/').pop();
  const customer = await db.customers.findById(customerId);
  return {
    mimeType: "application/json",
    content: JSON.stringify(customer)
  };
});

// Register tools
server.tool({
  name: "update_customer",
  description: "Update customer information",
  inputSchema: {
    type: "object",
    properties: {
      customerId: { type: "string" },
      updates: { type: "object" }
    }
  }
}, async (args) => {
  const result = await db.customers.update(
    args.customerId,
    args.updates
  );
  return { success: true, customerId: result.id };
});

server.listen(3000);

Python Server Example

from mcp.server import MCPServer, Resource, Tool

server = MCPServer(name="Analytics Integration")

@server.resource("analytics://metrics/{metric_name}")
async def get_metric(uri: str) -> Resource:
    metric_name = uri.split('/')[-1]
    data = await analytics_db.get_metric(metric_name)
    return Resource(
        uri=uri,
        mimeType="application/json",
        content=json.dumps(data)
    )

@server.tool("calculate_forecast")
async def calculate_forecast(time_range: str, metric: str) -> dict:
    forecast = await ml_model.predict(metric, time_range)
    return {"forecast": forecast, "confidence": 0.85}

if __name__ == "__main__":
    server.run(host="0.0.0.0", port=8080)

Security & Permissions

Authentication

MCP servers support multiple auth methods:

Bearer Token

{
  "auth": {
    "type": "bearer",
    "token": "YOUR_TOKEN"
  }
}

OAuth 2.0

{
  "auth": {
    "type": "oauth2",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "tokenUrl": "https://auth.example.com/token"
  }
}

API Key

{
  "auth": {
    "type": "apiKey",
    "key": "YOUR_API_KEY",
    "header": "X-API-Key"
  }
}

Access Control

Restrict agent access to specific resources:

{
  "permissions": {
    "resources": {
      "allow": ["file:///public/*"],
      "deny": ["file:///private/*"]
    },
    "tools": {
      "allow": ["search_*", "read_*"],
      "deny": ["delete_*", "admin_*"]
    }
  }
}

Audit Logging

All MCP interactions are logged:

{
  "timestamp": "2026-01-26T10:40:00Z",
  "agentId": "agent-123",
  "serverId": "mcp-server-123",
  "action": "tool_call",
  "toolName": "create_support_ticket",
  "success": true,
  "duration": 245
}

Monitoring & Debugging

Server Health

Check MCP server status:

GET /api/v1/mcp/servers/{serverId}/health

{
  "status": "healthy",
  "latency": 45,
  "uptime": 2592000,
  "lastCheck": "2026-01-26T10:45:00Z",
  "metrics": {
    "resourceQueries": 1250,
    "toolCalls": 487,
    "errors": 3
  }
}

Debug Mode

Enable detailed logging for troubleshooting:

PUT /api/v1/mcp/servers/{serverId}/debug

{
  "debug": true,
  "logLevel": "verbose",
  "includePayloads": true
}

Common Issues

Connection Failures

Verify server endpoint is accessible
Check authentication credentials
Ensure firewall rules allow traffic

Tool Execution Errors

Validate tool input schema
Check server-side error logs
Test tool independently

Resource Access Denied

Review agent permissions
Verify resource URIs are correct
Check MCP server access controls

Best Practices

Resource Design

✅ Good Practices:

Use descriptive resource URIs
Provide clear descriptions
Include relevant metadata
Cache frequently accessed resources

❌ Avoid:

Exposing sensitive data without auth
Large resources without pagination
Ambiguous resource naming

Tool Design

✅ Good Practices:

Clear, action-oriented tool names
Comprehensive input schemas
Detailed descriptions
Idempotent operations when possible

❌ Avoid:

Destructive operations without confirmation
Tools with unclear side effects
Missing error handling

Performance

Cache MCP responses when appropriate
Implement timeouts for tool calls
Use pagination for large datasets
Monitor resource query latency

Security

Always use HTTPS for MCP endpoints
Rotate credentials regularly
Implement rate limiting on servers
Audit tool executions
Use least-privilege access

Examples

Customer Support Integration

Enable agents to access support tickets and create new ones:

Setup:

POST /api/v1/mcp/servers

{
  "name": "Support System",
  "endpoint": "https://mcp.example.com/support",
  "capabilities": {
    "resources": true,
    "tools": true
  }
}

Usage:

User: "What's the status of ticket #12345?"

Agent: [Queries resource: support://tickets/12345]
       "Ticket #12345 is currently in progress. 
        It was assigned to Sarah and last updated 2 hours ago."

User: "Create a new ticket for a billing issue."

Agent: [Calls tool: create_ticket]
       "I've created ticket #12346 for your billing issue. 
        You can track it at https://support.example.com/12346"

Database Analytics

Query live database metrics:

POST /api/mcp/resources/query

{
  "serverId": "mcp-postgres-prod",
  "resourceUri": "db://analytics/metrics/daily_users",
  "agentId": "agent-analytics"
}

Response:

{
  "data": {
    "metric": "daily_active_users",
    "value": 15420,
    "change": "+5.2%",
    "timestamp": "2026-01-26T00:00:00Z"
  }
}

API Reference

List MCP Servers

GET /api/v1/mcp/servers

Get Server Details

GET /api/v1/mcp/servers/{serverId}

Update Server Configuration

PUT /api/v1/mcp/servers/{serverId}

Remove Server

DELETE /api/v1/mcp/servers/{serverId}

Test Connection

POST /api/v1/mcp/servers/{serverId}/test

SDK Support

TypeScript/JavaScript

import { TwigAI } from '@twig-ai/sdk';

const twig = new TwigAI({ apiKey: process.env.TWIG_API_KEY });

// Add MCP server
await twig.mcp.addServer({
  name: "Custom Integration",
  endpoint: "https://mcp.example.com",
  auth: { type: "bearer", token: "TOKEN" }
});

// Query with MCP enabled
const response = await twig.chat({
  prompt: "Get latest customer data",
  agentId: "agent-123",
  mcpEnabled: true
});

Python (Coming Soon)

from twig_ai import TwigAI

twig = TwigAI(api_key=os.environ["TWIG_API_KEY"])

# Add MCP server
twig.mcp.add_server(
    name="Custom Integration",
    endpoint="https://mcp.example.com",
    auth={"type": "bearer", "token": "TOKEN"}
)

Resources

Documentation

Tools & Libraries

Community

Next Steps

Explore REST API Overview to understand Twig's API fundamentals
Review Authentication to secure your integrations
Check Rate Limits for MCP usage quotas
Browse Pre-built Integrations to get started quickly

For custom MCP server development, refer to the official MCP documentation and our code examples.

PreviousDeveloper API & MCP NextREST API Overview

Last updated 8 days ago

hashtagOverview

hashtagKey Benefits

hashtagArchitecture

hashtagGetting Started

hashtagPrerequisites

hashtagQuick Setup

hashtagMCP Concepts

hashtagResources

hashtagTools

hashtagPrompts

hashtagConfiguration

hashtagConnecting an MCP Server

hashtagAPI Endpoint

hashtagRequest Body

hashtagResponse

hashtagAssigning to Agents

hashtagUsing MCP Resources

hashtagQuery Resources

hashtagManual Resource Access

hashtagUsing MCP Tools

hashtagAutomatic Tool Execution

hashtagTool Execution Flow

hashtagPre-built MCP Servers

hashtagAvailable Integrations

hashtagInstalling Pre-built Servers

hashtagBuilding Custom MCP Servers

hashtagServer Implementation

hashtagExample: Node.js Server

hashtagPython Server Example

hashtagSecurity & Permissions

hashtagAuthentication

hashtagBearer Token

hashtagOAuth 2.0

hashtagAPI Key

hashtagAccess Control

hashtagAudit Logging

hashtagMonitoring & Debugging

hashtagServer Health

hashtagDebug Mode

hashtagCommon Issues

hashtagConnection Failures

hashtagTool Execution Errors

hashtagResource Access Denied

hashtagBest Practices

hashtagResource Design

hashtagTool Design

hashtagPerformance

hashtagSecurity

hashtagExamples

hashtagCustomer Support Integration

hashtagDatabase Analytics

hashtagAPI Reference

hashtagList MCP Servers

hashtagGet Server Details

hashtagUpdate Server Configuration

hashtagRemove Server

hashtagTest Connection

hashtagSDK Support

hashtagTypeScript/JavaScript

hashtagPython (Coming Soon)

hashtagResources

hashtagDocumentation

hashtagTools & Libraries

hashtagCommunity

hashtagNext Steps

Overview

Key Benefits

Architecture

Getting Started

Prerequisites

Quick Setup

MCP Concepts

Resources

Tools

Prompts

Configuration

Connecting an MCP Server

API Endpoint

Request Body

Response

Assigning to Agents

Using MCP Resources

Query Resources

Manual Resource Access

Using MCP Tools

Automatic Tool Execution

Tool Execution Flow

Pre-built MCP Servers

Available Integrations

Installing Pre-built Servers

Building Custom MCP Servers

Server Implementation

Example: Node.js Server

Python Server Example

Security & Permissions

Authentication

Bearer Token

OAuth 2.0

API Key

Access Control

Audit Logging

Monitoring & Debugging

Server Health

Debug Mode

Common Issues

Connection Failures

Tool Execution Errors

Resource Access Denied

Best Practices

Resource Design

Tool Design

Performance

Security

Examples

Customer Support Integration

Database Analytics

API Reference

List MCP Servers

Get Server Details

Update Server Configuration

Remove Server

Test Connection

SDK Support

TypeScript/JavaScript

Python (Coming Soon)

Resources

Documentation

Tools & Libraries

Community

Next Steps