MCP Server Connection Guide

systemprompt can connect to any MCP (Model Context Protocol) server that implements the Streamable HTTP transport. This guide covers everything you need to know about establishing and maintaining server connections.

Overview

MCP servers provide tools and capabilities that systemprompt can leverage through voice commands. The connection process is designed to be flexible, supporting both local development servers and remote production endpoints.

Connection Requirements

• MCP Compliance: Server must implement MCP protocol
• HTTP Transport: SSE or WebSocket support
• Network Access: Server must be reachable
• Valid Endpoint: Correct URL format
• Authentication: If required by server

Transport Types

Server-Sent Events (SSE)

The default and most common transport:

Characteristics

• Unidirectional: Server to client
• Simple HTTP: Works everywhere
• Auto-reconnect: Built-in resilience
• Text-based: Easy to debug
• Wide support: Most MCP servers

When to Use

• Default choice
• Behind firewalls
• Simple request/response
• Maximum compatibility

WebSocket

For bidirectional communication:

Characteristics

• Bidirectional: Two-way communication
• Persistent: Long-lived connections
• Low latency: Real-time updates
• Binary support: Efficient data transfer
• Stateful: Connection awareness

When to Use

• Real-time features
• Streaming data
• Interactive tools
• High-frequency updates

Connection Process

Step-by-Step Guide

1. Navigate to MCP Servers

   • Open app
   • Tap MCP tab
   • View server list

2. Add New Server

   • Tap "+" button
   • Choose server type
   • Enter details

3. Configure Connection

   • Server name
   • Endpoint URL
   • Transport type
   • Authentication

4. Test Connection

   • Tap "Test"
   • Verify success
   • Check tools loaded

5. Save and Connect

   • Save configuration
   • Auto-connect option
   • Monitor status

URL Formats

Remote Servers

https://api.example.com/mcp
https://mcp.service.io/v1/sse
https://realtime.example.com/mcp

Local Development

http://localhost:3000/mcp
http://192.168.1.100:8080/mcp
http://host.docker.internal:3000/mcp

With Authentication

https://token:secret@api.example.com/mcp
https://api.example.com/mcp?api_key=xxx

Local Server Connections

Development Setup

Connecting to local MCP servers:

1. Start your MCP server

   npm run mcp-server
   # Server running on http://localhost:3000/mcp

2. Find your IP address

   • Mac: ifconfig | grep inet
   • Windows: ipconfig
   • Linux: ip addr show

3. Configure in systemprompt

   • Use IP instead of localhost
   • Example: http://192.168.1.100:3000/mcp
   • Ensure same network

Network Considerations

Same Network Required

• Phone and computer on same WiFi
• No VPN interference
• Firewall allows connection
• Port not blocked

Troubleshooting Local

• Ping IP from phone browser
• Check firewall settings
• Verify server is running
• Try different port

Remote Server Connections

Production Servers

Connecting to cloud MCP servers:

Requirements

• HTTPS endpoint (recommended)
• Valid SSL certificate
• Stable internet connection
• Proper authentication

Best Practices

• Use HTTPS always
• Implement rate limiting
• Monitor availability
• Document endpoint

CDN and Proxies

Working with infrastructure:

CloudFlare

• Enable WebSocket support
• Configure timeout appropriately
• Bypass cache for MCP endpoint
• Monitor rate limits

Reverse Proxy

• Pass correct headers
• Maintain connection
• Handle upgrades
• Preserve authentication

Connection Lifecycle

Initial Connection

What happens when connecting:

1. Validate URL format and accessibility
2. Establish transport SSE or WebSocket
3. Authenticate if required
4. Negotiate protocol version check
5. Enumerate tools discover capabilities
6. Ready state connection active

Maintaining Connection

systemprompt handles:

• Heartbeat: Keep connection alive
• Auto-reconnect: On disconnect
• Backoff strategy: Prevent hammering
• State recovery: Resume operations
• Error handling: Graceful degradation

Connection States

Monitor these states:

• Connecting: Yellow indicator
• Connected: Green indicator
• Disconnected: Red indicator
• Reconnecting: Yellow pulsing
• Error: Red with message

Authentication During Connection

No Authentication

For open servers:

Server: Local Dev
URL: http://192.168.1.100:3000/mcp
Auth: None

Token Authentication

For secured servers:

Server: Production API
URL: https://api.example.com/mcp
Auth: Bearer Token
Token: [Secure Storage]

OAuth Flow

For OAuth servers:

1. Configure OAuth settings
2. Initiate connection
3. Complete OAuth flow
4. Connection established
5. Token stored securely

Advanced Connection Options

Custom Headers

Add headers to requests:

X-Client-Version: 1.0.0
X-Request-ID: unique-id
X-Custom-Header: value

Timeout Configuration

Adjust for your needs:

• Connection timeout: Initial connect
• Request timeout: Tool execution
• Idle timeout: Keep-alive
• Retry delay: Between attempts

Retry Policies

Configure retry behavior:

• Max attempts: Number of retries
• Backoff: Linear or exponential
• Retry conditions: Which errors
• Circuit breaker: Prevent overload

Troubleshooting Connections

Common Issues

"Connection refused"

• Server not running
• Wrong port/URL
• Firewall blocking
• Network unreachable

"Authentication failed"

• Invalid credentials
• Expired token
• Wrong auth method
• Missing permissions

"Timeout error"

• Server too slow
• Network issues
• Increase timeout
• Check server load

"SSL certificate error"

• Invalid certificate
• Self-signed cert
• Expired certificate
• Wrong domain

Debug Tools

Connection Test

1. Use test button
2. View detailed logs
3. Check each step
4. Identify failure point

Network Inspector

• View raw requests
• Check responses
• Monitor timing
• Inspect headers

Recovery Steps

1. Verify basics first
2. Test in browser if possible
3. Check server logs for errors
4. Try minimal config remove complexity
5. Contact support with details

Best Practices

Server URLs

• Use HTTPS for remote servers
• Include path if required
• No trailing slash unless needed
• Encode special chars properly
• Validate format before saving

Connection Management

• Name servers clearly for identification
• Group by purpose or environment
• Document requirements in notes
• Test before saving always
• Monitor health regularly

Security

• Rotate credentials periodically
• Use minimal permissions needed
• Audit connections regularly
• Remove unused servers
• Monitor access logs

Performance Optimization

Connection Pooling

systemprompt optimizes by:

• Reusing connections
• Multiplexing requests
• Efficient reconnection
• Resource management

Bandwidth Considerations

For mobile networks:

• Choose SSE over WebSocket
• Enable compression
• Limit concurrent connections
• Monitor data usage

Server Examples

GitHub Official

URL: https://api.githubcopilot.com/mcp/
Transport: SSE
Auth: OAuth 2.0

Custom Node.js Server

URL: http://192.168.1.50:3000/mcp
Transport: SSE
Auth: Bearer Token

Corporate MCP Gateway

URL: https://mcp-gateway.company.com/v1
Transport: WebSocket
Auth: SAML SSO

Master server connections to unlock the full power of MCP!