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

1. Choose or Build an MCP Server
   • Use pre-built servers for common integrations
   • Build custom servers for proprietary systems
2. Configure Connection
   • Register your MCP server endpoint
   • Set up authentication credentials
   • Define available resources and tools
3. 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:

1. Identifies need for policy document
2. Queries MCP server for file:///docs/refund-policy.pdf
3. Retrieves content
4. 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:

1. Identifies need to create ticket
2. Calls create_support_ticket tool
3. Receives confirmation
4. 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": "admin@company.com"
    }
  }'

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

• MCP Protocol Specification
• Official MCP SDK
• Twig REST API

Tools & Libraries

• MCP TypeScript SDK
• MCP Python SDK
• MCP Server Examples

Community

• MCP Community Forum
• Example Integrations
• Twig Developer Discord

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.

---

Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the ask query parameter:

GET /dev/product/developer-api/mcp.md?ask=<question>

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.