Skills
skills/smithery.ai/Smithery

Smithery

SKILL.md

Smithery Skill Reference

Product summary

Smithery is a managed platform for connecting AI agents to Model Context Protocol (MCP) servers. Instead of implementing MCP protocol directly, handling OAuth flows, and managing credentials yourself, Smithery Connect provides a REST API and SDK that abstracts away authentication, token refresh, and connection lifecycle management. Use Smithery to add tools to LLMs, publish MCP servers for distribution, manage multi-user connections with scoped tokens, and integrate with frameworks like Vercel AI SDK. Key files: @smithery/api (SDK), @smithery/cli (CLI), SMITHERY_API_KEY (environment variable). Primary docs: https://smithery.ai/docs

When to use

Reach for Smithery when:

  • Building AI agents that need access to external tools via MCP servers (GitHub, Exa search, Browserbase, etc.)
  • You need to handle OAuth flows without managing redirect URIs, client IDs, or token refresh
  • Building multi-user applications where different users connect to different MCP servers
  • Publishing your own MCP server for distribution and discovery
  • Integrating MCP tools with Vercel AI SDK or other LLM frameworks
  • You need to scope API tokens for browser/mobile clients with fine-grained permissions
  • Managing long-lived connections to MCP servers with automatic credential storage and refresh

Quick reference

CLI Commands

Command Purpose
smithery auth login Authenticate with Smithery (required for some operations)
smithery mcp search [term] Search the Smithery registry for MCP servers
smithery mcp add <url> Add an MCP connection (remote by default)
smithery mcp add <url> --client <name> Add MCP to local client (claude, cursor, etc.)
smithery mcp list List your connections
smithery mcp get <id> Get connection details
smithery mcp remove <ids...> Remove connections
smithery mcp publish <url> -n <name> Publish an MCP server to registry
smithery tool list <connection-id> List available tools for a connection
smithery tool call <connection-id> <tool-name> '<args>' Call a tool on a connection
smithery auth token --policy '[...]' Generate scoped service tokens

SDK Imports

import Smithery from '@smithery/api';
import { createConnection } from '@smithery/api/mcp';
import { createMCPClient } from '@ai-sdk/mcp';

Key Concepts

Concept Definition
Namespace Globally unique identifier grouping connections, servers, and skills (e.g., my-app, my-app-staging)
Connection Long-lived session to an MCP server with auto-managed credentials and OAuth
Transport Communication channel between client and server (HTTP, STDIO, or custom)
Service Token Scoped, short-lived token for browser/mobile clients with fine-grained permissions
API Key Full-access token for backend use only (never expose to untrusted clients)

Authentication Methods

Method Use Case Scope
API Key Backend only Full namespace access
Service Token Browser, mobile, agents Scoped to specific connections/operations

Decision guidance

When to use API Key vs Service Token

Scenario Use API Key Use Service Token
Backend server calling Smithery API ✓
Browser/mobile app calling Smithery ✓
Agent with full namespace access ✓
Agent with access to specific user's connections ✓
Long-lived credentials ✓
Short-lived, scoped access ✓

When to use CLI vs SDK

Task CLI SDK
Quick testing/exploration ✓
Integrating into application code ✓
Managing connections programmatically ✓
One-off server connection ✓
Multi-user application ✓

When to publish via URL vs CLI

Approach When to Use
URL method (smithery.ai/new) Server already deployed; want UI-guided publishing
CLI method (smithery mcp publish) Automating publishing; custom config schema needed
Static server card (/.well-known/mcp/server-card.json) Automatic scanning fails; auth wall or required config

Workflow

1. Connect to an MCP Server (SDK)

import { createConnection } from '@smithery/api/mcp';
import { createMCPClient } from '@ai-sdk/mcp';

// Create a connection
const { transport } = await createConnection({
  mcpUrl: 'https://exa.run.tools',
  namespace: 'my-app',
  connectionId: 'exa-search'
});

// Get an MCP client
const mcpClient = await createMCPClient({ transport });
const tools = await mcpClient.tools();

2. Handle OAuth Authorization

When createConnection() throws SmitheryAuthorizationError:

import { SmitheryAuthorizationError } from '@smithery/api/mcp';

try {
  const { transport } = await createConnection({
    mcpUrl: 'https://github.run.tools'
  });
} catch (error) {
  if (error instanceof SmitheryAuthorizationError) {
    // Redirect user to error.authorizationUrl
    // Save error.connectionId for retry after auth completes
    redirect(error.authorizationUrl);
  }
}

// After user authorizes, retry with saved connectionId
const { transport } = await createConnection({
  connectionId: savedConnectionId
});

3. Configure Servers with API Keys

For servers requiring API keys or project IDs:

const conn = await smithery.connections.set('my-browserbase', {
  namespace: 'my-app',
  mcpUrl: 'https://browserbase.run.tools?browserbaseProjectId=your-project-id',
  headers: {
    'browserbaseApiKey': 'your-browserbase-api-key'
  }
});
// conn.status.state === "connected" — ready immediately

Check the server's page on smithery.ai to see which config values go as headers (API keys) vs query parameters.

4. Create Scoped Service Tokens

For browser/mobile clients, mint short-lived tokens with specific permissions:

smithery auth token --policy '[{
  "namespaces": "my-app",
  "resources": "connections",
  "operations": ["read", "execute"],
  "metadata": { "userId": "user-123" },
  "ttl": "1h"
}]'

5. Publish an MCP Server

Option A: Via Web UI

  1. Go to smithery.ai/new
  2. Enter your server's public HTTPS URL
  3. Complete the publishing flow

Option B: Via CLI

smithery mcp publish "https://your-server.com/mcp" -n @your-org/your-server

Option C: With Custom Config Schema

smithery mcp publish "https://your-server.com/mcp" \
  -n @your-org/your-server \
  --config-schema '{"type":"object","properties":{"apiKey":{"type":"string"}}}'

6. Provide Server Metadata (if scanning fails)

Create /.well-known/mcp/server-card.json:

{
  "serverInfo": {
    "name": "Your Server Name",
    "version": "1.0.0"
  },
  "authentication": {
    "required": true,
    "schemes": ["oauth2"]
  },
  "tools": [
    {
      "name": "search",
      "description": "Search for information",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      }
    }
  ],
  "resources": [],
  "prompts": []
}

7. Integrate with Vercel AI SDK

import { createMCPClient } from '@ai-sdk/mcp';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { createConnection } from '@smithery/api/mcp';

const { transport } = await createConnection({
  mcpUrl: 'https://exa.run.tools'
});

const mcpClient = await createMCPClient({ transport });
const tools = await mcpClient.tools();

const { text } = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools,
  prompt: 'Search for the latest news about MCP.'
});

await mcpClient.close();

Common gotchas

  • Never expose API keys to browsers or untrusted clients. Use scoped service tokens instead.
  • Credentials are write-only. Once stored, they can only be used to execute requests—they cannot be read back. This is intentional for security.
  • Restart your AI client after adding/removing servers. Changes don't take effect until the client restarts.
  • OAuth tokens refresh automatically. If refresh fails, connection status changes to auth_required—retry the OAuth flow.
  • Namespace is required for multi-user setups. If omitted, the SDK uses the first existing namespace or creates one. Explicitly set namespace to avoid conflicts.
  • Config values go in specific places. Check the server's page on smithery.ai to see whether each config value is a header (API keys) or query parameter (project IDs, etc.).
  • Deep links require URL encoding. The config parameter must be base64-encoded JSON. Use encodeURIComponent() when constructing deep links.
  • Service token TTL is required. Always specify ttl (e.g., "1h", "30m") when minting tokens. Tokens without TTL will not be created.
  • Metadata filtering is case-sensitive. When listing connections with metadata.userId=alice, the key and value must match exactly.
  • Automatic scanning may fail for auth-required servers. Provide a static server card at /.well-known/mcp/server-card.json if Smithery can't scan your server automatically.

Verification checklist

Before submitting work with Smithery:

  • API keys and secrets are stored in environment variables, never hardcoded
  • Service tokens are scoped to specific namespaces, resources, and operations
  • OAuth authorization errors are caught and handled with SmitheryAuthorizationError
  • Namespace is explicitly set for multi-user applications
  • Connection IDs are saved before redirecting users to OAuth authorization URLs
  • Server configuration values (API keys, project IDs) are placed in correct location (headers vs query params)
  • CLI commands use --verbose flag during debugging
  • Published servers include either automatic metadata or a static server card
  • Credentials are never logged or exposed in error messages
  • Token TTL is set appropriately (shorter for public clients, longer for backend)

Resources

Comprehensive navigation: https://smithery.ai/docs/llms.txt

Critical documentation pages:

  • Connect to MCPs — Full guide to creating connections, handling OAuth, and using transports
  • Token Scoping — Fine-grained access control for service tokens
  • Publish MCP Servers — Publishing servers to the registry with metadata and config schemas

For additional documentation and navigation, see: https://smithery.ai/docs/llms.txt

Weekly Installs
1
Source
smithery.ai/docs
First Seen
10 days ago
Installed on
windsurf1
amp1
cline1
opencode1
cursor1
kimi-cli1