Skip to main content
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

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
1

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
];
2

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

​
Tool Discovery Failures

If connection succeeds but no tools are discovered:
1

Check Documentation

Review the MCP server documentation for available tools
2

Verify Path

Ensure the server path is correct (should end with /mcp)
3

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:
  1. Verify the server supports browser-based connections
  2. Check if additional headers are needed in the configuration
  3. Consider using a proxy server for the connection

​
Debugging Guide

1

Enable Debug Logging

mcp: { debug: true }
2

Check Browser Console

Look for:
  • CSP violations
  • Network errors
  • CORS issues
3

Verify Network Tab

Check that:
  • Request is being sent to correct URL
  • API key and profile are in query params
  • Response status and body
4

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 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

Smithery Docs

Official Smithery documentation

MCP Specification

Model Context Protocol spec

Debug Guide

Sammy Three MCP debugging
⌘I