MCP Servers

MCP Servers (Model Context Protocol) allow you to extend your agent's capabilities by connecting it to external services that provide additional tools. With MCP, you integrate APIs, databases, third-party systems, and more through a standardized protocol.

---

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes communication between language models (LLMs) and external services. Think of it as a universal "plug" for AI integrations.

Capability	Description
Access external tools	Execute actions in third-party systems
Query real-time data	Get updated information from APIs and databases
Integrate enterprise services	Connect to CRMs, ERPs, calendars
Expand functionality	Add custom capabilities without modifying the agent

MCP vs. API Integration

• MCP Servers: Standardized protocol, richer capabilities, requires an MCP server
• API Integration: Simpler setup, single REST calls, no server needed

Use MCP when you need complex tool ecosystems. Use API Integration for simple REST endpoints.

---

How MCP Works

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   SipPulse  │────▶│  SipPulse   │────▶│   MCP Server    │
│    Agent    │     │     AI      │     │   (External)    │
└─────────────┘     └─────────────┘     └─────────────────┘
                           │                     │
                           ▼                     ▼
                    ┌─────────────┐       ┌───────────┐
                    │   Tool      │       │  External │
                    │   Results   │◀──────│   System  │
                    └─────────────┘       └───────────┘

Flow:

1. Agent receives a user request
2. LLM decides to use a tool from the MCP server
3. SipPulse AI connects to the MCP server
4. Server executes the tool and returns results
5. Agent uses results to respond to the user

---

Configuring an MCP Server

Accessing Configuration

1. Navigate to Agents in the side menu
2. Select or create an agent
3. Go to the Tools section
4. Click MCP Servers

Adding a Server

1. Click Add MCP Server
2. Fill in the required fields:

Field	Description	Example
Name	Identifier for the server	"Google Calendar"
URL	MCP server endpoint	https://mcp.example.com/api
Transport	Communication protocol	HTTP, SSE, WebSocket
Headers	Authentication headers	Authorization: Bearer ...

3. Click Create to add the server

Transport Types

Transport	Description	Best For
HTTP	Traditional request/response	Quick, synchronous tools
SSE	Server-Sent Events	Streaming responses, long operations
WebSocket	Persistent bidirectional	Real-time communication

Automatic Detection

Transport is auto-detected from URL patterns:

• /sse in URL → SSE
• ws:// or wss:// → WebSocket
• Otherwise → HTTP

Authentication

For servers requiring authentication, add headers:

1. In Headers section, click Add Header
2. Enter header name and value

Common patterns:

Header	Value	Use Case
Authorization	Bearer {token}	OAuth/JWT APIs
X-API-Key	{your_key}	API key authentication
X-Custom-Header	{value}	Custom requirements

---

Managing Tools

Syncing Tools

When the MCP server updates its available tools:

1. Locate the server in the list
2. Click the sync icon (↻)
3. New tools are loaded automatically

Enabling/Disabling Tools

Control which tools the agent can access:

1. Expand the server (click the chevron)
2. Toggle individual tools on/off
3. Disabled tools won't be available to the agent

Performance Optimization

Disable unused tools. Fewer tools means:

• Faster decision-making by the LLM
• Lower token usage
• More focused agent behavior

Disabling a Server

To temporarily disable all tools without removing the server:

• Toggle the switch next to the server name
• All server tools become unavailable

---

Example: Google Calendar Integration

Step 1: Configure Server

Field	Value
Name	Google Calendar
URL	https://mcp-calendar.example.com/api
Transport	HTTP

Step 2: Add Authentication

Header	Value
Authorization	Bearer {oauth_token}

Step 3: Available Tools

After sync, typical calendar tools include:

Tool	Purpose
get_calendar_events	List upcoming events
create_event	Schedule new event
update_event	Modify existing event
delete_event	Remove event
check_availability	Find free time slots

Step 4: Agent in Action

User: "Schedule a meeting for tomorrow at 2 PM called 'Project Review'"

Agent:

1. Recognizes scheduling intent
2. Calls create_event tool with parameters
3. Receives confirmation from MCP server
4. Responds: "Done! I've scheduled 'Project Review' for tomorrow at 2 PM."

---

Example: CRM Integration

Configuration

Field	Value
Name	Salesforce CRM
URL	https://mcp-salesforce.example.com/api
Transport	HTTP
Authorization	Bearer {sf_access_token}

Available Tools

Tool	Purpose
search_contacts	Find contacts by name/email
get_contact_details	Full contact information
create_lead	Add new lead
update_opportunity	Modify deal status
log_activity	Record interaction

Conversation Example

User: "Can you find John Smith's contact info?"

Agent: [Uses search_contacts: "John Smith"] "I found John Smith in your CRM. He's the VP of Engineering at Acme Corp. His email is john@acme.com and his phone is (555) 123-4567. Would you like me to log this call as an activity?"

---

Best Practices

Security

Practice	Why
Never expose credentials in instructions	Prevents data leaks in prompts
Use HTTPS for all connections	Encrypts data in transit
Rotate tokens regularly	Limits damage from compromised credentials
Limit permissions to necessary tools	Principle of least privilege

Performance

• Keep few servers per agent - Each server adds latency
• Disable unused tools - Reduces LLM decision complexity
• Monitor server latency - Slow servers degrade experience
• Configure appropriate timeouts - Prevent hanging requests

Maintenance

• Document configurations - Helps troubleshooting
• Test after server updates - Catch breaking changes
• Monitor execution logs - Identify failures early
• Version your MCP servers - Enable rollbacks

---

Troubleshooting

Server Won't Connect

1. Verify URL is correct and accessible
2. Confirm authentication headers are valid
3. Test endpoint directly with curl:

   curl -X POST https://your-mcp-server.com/api \
     -H "Authorization: Bearer your_token" \
     -H "Content-Type: application/json"

4. Check firewall rules if self-hosted

Tools Not Appearing

1. Click sync to reload tools
2. Verify MCP server returns tool list correctly
3. Confirm response follows MCP specification
4. Check server logs for errors

Execution Errors

1. Check thread execution logs
2. Verify tool parameters are correct
3. Test tool directly on MCP server
4. Review server-side error logs

Slow Response Times

1. Profile MCP server performance
2. Check network latency to server
3. Consider caching for repeated queries
4. Use SSE transport for long operations

---

Creating Your Own MCP Server

If you want to create a custom MCP server for your tools:

Requirements

• Implement the MCP specification
• Expose /tools endpoint listing available tools
• Handle tool execution requests
• Return structured responses

Resources

• MCP Specification - Official protocol documentation
• MCP SDKs - Official SDKs for various languages

Alternative: Manual Tools

For simpler integrations where you control the backend, consider Manual Tools. They're easier to implement and don't require a full MCP server.

---

Related Documentation

• Tools Overview - Understanding agent tools
• API Integration - Simpler REST integrations
• Manual Tools - Custom backend logic
• Testing Agents - Validate tools in playground