​

MCP (Model Context Protocol)

​

Overview

• External Tool Access - Connect to third-party services and APIs
• Data Source Integration - Access databases, file systems, and cloud storage
• Custom Functionality - Add specialized tools for your specific use cases
• Standardized Interface - Use a consistent protocol for all integrations
• Secure Authentication - Support for OAuth 2.0 and custom headers

​

How It Works

​

1. MCP Server Connection

1. Server Registration - The server is registered with your agent configuration
2. Tool Discovery - The agent discovers available tools from the MCP server
3. Tool Integration - Tools become available to the agent during conversations
4. Dynamic Execution - The agent can call these tools as needed

​

2. Tool Execution Flow

User Query → Agent → MCP Tool Call → MCP Server → External System → Response → Agent → User

​

3. Multiple Servers

• Each server provides its own set of tools
• Tools are prefixed with the server name (e.g., sentry_get_errors)
• Servers can be enabled or disabled independently

​

Quick Start

​

Adding Popular MCP Servers

1. Navigate to Agents in the sidebar
2. Select or create an agent
3. Click Edit to open the agent builder
4. Go to the MCP tab
5. In the Quick Add Popular Servers section, click on a server tile to add it

​

Popular Servers

​

Sentry

• URL: https://mcp.sentry.dev/mcp
• Transport: HTTP
• Authentication: OAuth 2.0
• Scopes: org:read project:write team:write event:write

• View error reports
• Monitor performance metrics
• Manage projects and teams
• Track events and issues

​

Video Tutorial

​

Adding Custom MCP Servers

​

Step 1: Access MCP Configuration

1. Navigate to Agents in the sidebar
2. Select or create an agent
3. Click Edit to open the agent builder
4. Go to the MCP tab
5. Scroll to the Advanced Configuration section

​

Step 2: Add New Server

1. Click Add Server button
2. The server configuration form will appear

​

Step 3: Configure Server Settings

​

Server Name

• Use lowercase letters and hyphens
• Be descriptive but concise
• Avoid special characters

​

Transport Type

• Standard HTTP requests
• Best for REST APIs and web services
• Supports request/response pattern

• Real-time streaming communication
• Best for live data feeds
• Supports one-way server-to-client streaming

​

Server URL

• https://api.example.com/mcp
• http://localhost:8000/mcp/
• https://mcp.example.com/v1

• https://api.example.com/sse
• https://stream.example.com/events

​

Step 4: Configure Authentication

​

No Authentication

​

OAuth 2.0

1. Select OAuth 2.0 as the authentication method
2. Enter OAuth Scopes (space-separated)
   • Example: read write admin
   • Example: org:read project:write team:write

• When a user interacts with the agent, they’ll be prompted to authorize
• Authorization is handled automatically
• Tokens are securely stored and refreshed as needed

​

Step 5: Custom Headers (Optional)

1. Click Add Header
2. Enter the header name (e.g., X-API-Key, Authorization)
3. Enter the header value
4. Add additional headers as needed

• X-API-Key: your-api-key
• Authorization: Bearer token
• X-Custom-Header: custom-value

​

Step 6: Enable/Disable Server

• Enabled: Server tools are available to the agent
• Disabled: Server tools are hidden but configuration is preserved

​

Step 7: Test Connection

1. Click the Test button to verify the connection
2. Wait for the test result:
   • Success: Server is reachable and configured correctly
   • Error: Check your configuration and network connectivity

​

Step 8: Save Configuration

1. Click Save to store your MCP server configuration
2. The server is now available to your agent

​

Managing MCP Servers

​

Viewing Configured Servers

• Server Count - Number of configured servers
• Server Status - Enabled/disabled status
• Server Names - List of all configured servers

​

Editing Server Configuration

1. Find the server in the Advanced Configuration section
2. Click to expand the server configuration
3. Modify any settings
4. Click Test to verify changes
5. Configuration is saved automatically

​

Removing Servers

1. Find the server you want to remove
2. Click the Remove icon (trash can)
3. Confirm removal
4. The server is removed from your agent configuration

​

Enabling/Disabling Servers

• Enable: Makes server tools available
• Disable: Hides server tools but preserves configuration

• Temporarily disabling problematic servers
• Testing different server configurations
• Managing server availability without removing configuration

​

Transport Types

​

HTTP (streamable_http)

• Connecting to REST APIs
• Standard request/response patterns
• Web services and microservices

• URL should point to the MCP endpoint
• Supports standard HTTP methods
• Works with most web services

URL: https://api.example.com/mcp
Transport: HTTP

​

SSE (Server-Sent Events)

• Real-time data streams
• Live updates and notifications
• One-way server-to-client communication

• URL should point to the SSE endpoint
• Server must support SSE protocol
• Automatic reconnection on disconnect

URL: https://stream.example.com/sse
Transport: SSE

​

Authentication Methods

​

No Authentication

• Public APIs
• Internal services
• Development/testing servers

• Select No Authentication
• No additional configuration needed

​

OAuth 2.0

• Third-party services (Sentry, Canva, etc.)
• User-specific data access
• Scoped permissions

1. Select OAuth 2.0
2. Enter OAuth scopes (space-separated)
3. Users will authorize on first use

• Sentry: org:read project:write team:write event:write
• Canva: asset:read asset:write design:read design:write
• Custom: read write admin

1. User interacts with agent
2. Agent needs MCP tool from OAuth-protected server
3. User is prompted to authorize
4. Authorization completes automatically
5. Token is stored securely
6. Future requests use stored token

​

Custom Headers

• API keys
• Custom authentication tokens
• Service-specific headers
• Request metadata

​

Adding Headers

1. In server configuration, find Custom Headers section
2. Click Add Header
3. Enter header name (e.g., X-API-Key)
4. Enter header value
5. Add more headers as needed

​

Common Header Patterns

Header: X-API-Key
Value: your-api-key-here

Header: Authorization
Value: Bearer your-token-here

Header: X-Service-Name
Value: your-service-identifier

​

Use Cases

​

Error Monitoring

{
  "server_name": "sentry",
  "transport": "streamable_http",
  "url": "https://mcp.sentry.dev/mcp",
  "auth_type": "oauth",
  "oauth_scopes": "org:read project:write team:write event:write"
}

• “Show me errors from the last 24 hours”
• “What’s the error rate for project X?”
• “List all unresolved issues”

​

Database Access

{
  "server_name": "postgres-db",
  "transport": "streamable_http",
  "url": "https://mcp.example.com/database",
  "auth_type": "oauth",
  "headers": {
    "X-Database-Name": "production"
  }
}

• “Query the users table”
• “Show me recent orders”
• “Get customer statistics”

​

File System Access

{
  "server_name": "filesystem",
  "transport": "streamable_http",
  "url": "https://mcp.example.com/files",
  "auth_type": "oauth"
}

• “List files in the documents folder”
• “Read the config file”
• “Search for files containing ‘error‘“

​

Real-Time Data Streams

{
  "server_name": "live-data",
  "transport": "sse",
  "url": "https://stream.example.com/sse",
  "auth_type": "oauth"
}

• “Show me live stock prices”
• “Monitor system metrics”
• “Track real-time events”

​

Best Practices

​

Server Naming

• Be Descriptive: Use clear, meaningful names
• Use Lowercase: Prefer lowercase with hyphens
• Avoid Special Characters: Stick to letters, numbers, and hyphens
• Be Consistent: Follow a naming convention

• sentry-monitoring
• postgres-production
• weather-api

• Server1
• my_mcp_server
• MCP-Server!!!

​

URL Configuration

• Use HTTPS: Always prefer secure connections
• Include Full Path: Specify the complete endpoint URL
• Test URLs: Verify URLs are accessible before saving
• Document Endpoints: Keep documentation of your endpoints

​

Authentication

• Use OAuth When Possible: More secure than API keys
• Minimize Scopes: Request only necessary permissions
• Store Securely: Tokens are handled automatically
• Test Authorization: Verify OAuth flow works correctly

​

Error Handling

• Test Connections: Use the Test button before saving
• Monitor Logs: Check for connection errors
• Handle Failures: Configure fallbacks for critical servers
• Disable Problematic Servers: Temporarily disable if needed

​

Performance

• Limit Server Count: Too many servers can slow down agents
• Disable Unused Servers: Keep only active servers enabled
• Optimize Headers: Only include necessary custom headers
• Monitor Response Times: Watch for slow MCP server responses

​

Troubleshooting

​

Connection Failures

• Incorrect URL
• Network connectivity issues
• Server not running
• Firewall blocking connection

• Verify URL is correct and accessible
• Check network connectivity
• Ensure server is running
• Review firewall rules

​

Authentication Errors

• Incorrect OAuth scopes
• Server doesn’t support OAuth
• User hasn’t authorized
• Token expired

• Verify OAuth scopes are correct
• Check server OAuth documentation
• Re-authorize the connection
• Check token expiration settings

​

Tools Not Available

• Server is disabled
• Connection not established
• Server not responding
• Tool discovery failed

• Enable the server
• Test the connection
• Verify server is running
• Check server logs

​

Timeout Errors

• Slow server response
• Network latency
• Server overloaded
• Incorrect timeout settings

• Check server performance
• Verify network speed
• Reduce server load
• Adjust timeout settings if configurable

​

Testing MCP Servers

​

Test Connection

1. Configure your MCP server
2. Click the Test button
3. Wait for results:
   • Success: Green indicator with success message
   • Error: Red indicator with error details

​

Test Results

• Connection successful message
• Server responding correctly
• Authentication working (if applicable)

• Connection timeout
• Authentication failed
• Invalid URL
• Server not responding

​

Interpreting Results

✓ Connection successful
MCP server connection tested successfully

✗ Connection failed
Failed to connect to server: Connection timeout

​

Security Considerations

​

OAuth Security

• Token Storage: Tokens are stored securely
• Token Refresh: Automatic token refresh when expired
• Scope Limitation: Request minimum necessary scopes
• User Authorization: Users must explicitly authorize

​

Custom Headers

• Sensitive Data: Don’t put sensitive data in headers if avoidable
• API Keys: Use OAuth when possible instead of API keys
• Header Visibility: Headers are stored in configuration
• Access Control: Limit who can view/edit MCP configurations

​

Network Security

• HTTPS Only: Always use HTTPS for production servers
• Internal Networks: Use internal URLs for private servers
• Firewall Rules: Configure firewalls appropriately
• VPN Access: Use VPN for secure connections when needed

​

Examples

​

Example 1: Sentry Integration

{
  "server_name": "sentry",
  "transport": "streamable_http",
  "url": "https://mcp.sentry.dev/mcp",
  "auth_type": "oauth",
  "oauth_scopes": "org:read project:write team:write event:write",
  "enabled": true
}

• Agent can monitor errors
• View performance metrics
• Manage Sentry projects

​

Example 2: Custom API Integration

{
  "server_name": "custom-api",
  "transport": "streamable_http",
  "url": "https://api.example.com/mcp",
  "auth_type": "oauth",
  "oauth_scopes": "read write",
  "headers": {
    "X-Client-ID": "your-client-id"
  },
  "enabled": true
}

• Agent can call custom API endpoints
• Access protected resources
• Use custom headers for identification

​

Example 3: Internal Service

{
  "server_name": "internal-service",
  "transport": "streamable_http",
  "url": "http://internal-service:8000/mcp",
  "auth_type": "none",
  "headers": {
    "X-Internal-Key": "internal-key-value"
  },
  "enabled": true
}

• Agent can access internal services
• No OAuth required
• Custom header for internal authentication

​

Related Features

• Toolkits - Built-in integrations and tools
• Tools - Custom tools and actions
• Agent Configuration - Configure agent behavior
• API Integration - Connect to external APIs

​

Support