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	auto
Headers	Authentication headers	Authorization: Bearer {{$MY_TOKEN}}

3. Click Create to add the server

Transport Types

Transport	Description	Best For
auto (default, recommended)	Streamable HTTP with automatic fallback to HTTP+SSE	Any modern server
HTTP	Streamable HTTP without fallback	Servers that only speak Streamable HTTP
SSE	HTTP+SSE	Servers that require SSE
WebSocket	Persistent bidirectional connection	Only entries created before; not offered for new servers

The per-server timeouts are 10 s to connect and 60 s per call (connect_ms and call_ms), configurable only through the API.

Prefer an MCP Connection

For OAuth servers or servers you reuse across several agents, create an MCP Connection in Settings > MCP connections and select it in the agent. The connection stores the credential and the tool cache once, instead of repeating the configuration in every agent.

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 {{$MY_TOKEN}}	OAuth/JWT APIs
X-API-Key	{{$MY_KEY}}	API key authentication
X-Custom-Header	{{$MY_VALUE}}	Custom requirements

The value inside {{$...}} is the name of a project secret, resolved in memory only at call time. See the Secrets Vault.

---

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 {{$GOOGLE_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 {{$SALESFORCE_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

When a call fails, the agent receives a typed error and the conversation continues. Use the table to know what to do:

Error	What it means	What to do
mcp_auth_required	The server asked for credentials, or the credential is no longer accepted	Fix the headers or reconnect the connection
mcp_unreachable	The server could not be reached: DNS, refused connection or network failure	Check the URL, the network and whether the server is up
mcp_timeout	The connection or the call exceeded the deadline	Raise connect_ms or call_ms, or check the server latency
mcp_tool_failed	The tool returned an error	Read the server message; the conversation continues and the model decides the next step

When the server asks for authentication, the connection badge becomes Needs re-authentication and the platform offers to reconnect.

---

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