Smithery is a platform that hosts MCP (Model Context Protocol) servers as remote endpoints. This guide covers integrating these servers with the Sammy Three package.
Quick Start Basic Smithery Configuration Basic Setup
Using Smithery SDK
const config : SammyAgentConfig = { mcp: { enabled: true , debug: true , servers: [ { name: 'hubspot' , type: 'streamableHttp' , streamableHttp: { url: 'https://server.smithery.ai/@BlackSand-Software/hubspot-mcp/mcp?api_key=YOUR_API_KEY&profile=YOUR_PROFILE' }, autoConnect: true } ] } };
Common Issues and Solutions Content Security Policy (CSP) Errors If you see: Refused to connect to 'https://server.smithery.ai/...' because it violates the following Content Security Policy directive
Update next.config.js
Add https://server.smithery.ai to your CSP connect-src directive: const connectSources = [ // ... other sources 'https://server.smithery.ai' , 'blob:' // Also needed for MCP ];
Restart Server
After updating next.config.js, you must restart your Next.js development server for the changes to take effect.
Authentication Issues
401 or 403 Errors Solutions:
Verify your API key is correct and active
Check that your profile has access to the requested MCP server
Ensure the API key and profile are properly URL-encoded in the connection string
Connection Timeout
Timeout Issues Solutions: mcp : { timeout : 60000 , // 60 seconds // ... }
Check if Smithery service is operational
Verify network connectivity
If connection succeeds but no tools are discovered:
Check Documentation
Review the MCP server documentation for available tools
Verify Path
Ensure the server path is correct (should end with /mcp)
Enable Debug Logging
mcp : { debug : true , // ... }
Security Considerations API Key Management Never hardcode API keys in your source code! Use environment variables instead.
SMITHERY_API_KEY = your-api-key-here SMITHERY_PROFILE = your-profile-here
Client-Side Security Since MCP connections are made from the browser, your API keys will be exposed in network requests. Consider these security measures:
Server-Side Proxy Route MCP requests through your backend
Token Rotation Use short-lived tokens
Restrict Permissions Limit what the API key can access
Monitor Usage Track API key usage for anomalies
CORS Considerations Smithery servers should handle CORS appropriately, but if you encounter CORS issues:
Verify the server supports browser-based connections
Check if additional headers are needed in the configuration
Consider using a proxy server for the connection
Debugging Guide
Check Browser Console
Look for:
CSP violations
Network errors
CORS issues
Verify Network Tab
Check that:
Request is being sent to correct URL
API key and profile are in query params
Response status and body
Test Connection Directly
curl "https://server.smithery.ai/@org/server/mcp?api_key=KEY&profile=PROFILE"
Complete HubSpot Integration Example Configuration
Event Monitoring
export const createSammyProviderConfig = ({ jwtToken , onTokenExpired , captureMethod , } : SammyProviderConfigParams ) : SammyAgentConfig => { return { // ... other config mcp: { enabled: true , debug: process . env . NODE_ENV === 'development' , timeout: 45000 , // HubSpot API calls might take longer autoReconnect: true , reconnectDelay: 5000 , maxReconnectAttempts: 3 , servers: [ { name: 'hubspot' , type: 'streamableHttp' , description: 'HubSpot CRM integration via Smithery' , autoConnect: true , streamableHttp: { url: `https://server.smithery.ai/@BlackSand-Software/hubspot-mcp/mcp?api_key= ${ process . env . NEXT_PUBLIC_SMITHERY_API_KEY } &profile= ${ process . env . NEXT_PUBLIC_SMITHERY_PROFILE } ` , headers: { // Add any additional headers if required 'User-Agent' : 'Sammy-Agent/1.0' } } } ] } }; };
mcp : { onEvent : ( event ) => { if ( event . type === 'mcp:server:connected' ) { console . log ( `Connected to Smithery server: ${ event . serverName } ` ); } if ( event . type === 'mcp:tool:discovered' ) { console . log ( `Discovered tool: ${ event . toolName } ` ); } if ( event . type === 'mcp:server:error' ) { console . error ( `Smithery connection error:` , event . error ); // Send to error tracking service } } }
MCP Configuration Reference Server Configuration interface MCPServerConfig { name : string ; // Server identifier type : 'streamableHttp' ; // Connection type description ?: string ; // Server description autoConnect ?: boolean ; // Auto-connect on startup streamableHttp : { url : string ; // Server endpoint URL headers ?: Record < string , string >; // Additional headers }; }
Global MCP Settings interface MCPConfig { enabled : boolean ; // Enable/disable MCP debug ?: boolean ; // Debug logging timeout ?: number ; // Connection timeout (ms) autoReconnect ?: boolean ; // Auto-reconnect on failure reconnectDelay ?: number ; // Delay between reconnects (ms) maxReconnectAttempts ?: number ; // Max reconnection attempts servers : MCPServerConfig []; // Server configurations onEvent ?: ( event : MCPEvent ) => void ; // Event handler }
Resources 
