Smithery

https://smithery.ai/docs
Admin
Smithery is a platform for developers to find and ship AI-native services that communicate with AI...
Tokens:83,379
Snippets:519
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://smithery.ai/docs/integrations/vercel_ai_sdk

Install the required packages for Vercel AI SDK and Smithery integration.

```bash
npm install ai @ai-sdk/mcp @ai-sdk/anthropic @smithery/api
```

--------------------------------

### Setup Stdio Client Transport

Source: https://smithery.ai/docs/use/deep-linking

Example implementation for setting up a Smithery client using a stdio transport based on deep link configuration.

```typescript
// Example with stdio transport
async function setupStdioMCP(url: string) {
  const config = handleDeepLink(url)
  const transport = new StdioClientTransport({
    command: config.command,
    args: config.args
  })
  
  const client = new Client({ name: "Test client" })
  await client.connect(transport)
  return client
}
```

--------------------------------

### Setup HTTP Client Transport

Source: https://smithery.ai/docs/use/deep-linking

Example implementation for setting up a Smithery client using an HTTP transport based on deep link configuration.

```typescript
// Example with HTTP transport
async function setupHttpMCP(url: string) {
  const config = handleDeepLink(url)
  const transport = new StreamableHTTPClientTransport(config.url)
  
  const client = new Client({ name: "Test client" })
  await client.connect(transport)
  return client
}
```

--------------------------------

### Smithery CLI Advanced Examples

Source: https://smithery.ai/docs/concepts/cli

Advanced usage examples including adding servers with configuration, removing servers, JSON output, and publishing MCP servers or bundles.

```bash
# Add an MCP server to Claude Desktop
smithery mcp add mcp-obsidian --client claude

# Add with pre-configured data (skips prompts)
smithery mcp add mcp-obsidian --client claude --config '{"vaultPath":"path/to/vault"}'

# Remove a server from a client
smithery mcp remove mcp-obsidian --client claude

# Search for MCP servers with JSON output
smithery --json mcp search "database"

# List tools from a specific connection
smithery tool list my-github

# Find tools by intent
smithery tool find "create issue"

# Call a tool with JSON arguments
smithery tool call my-github create_issue '{"title":"Bug fix","body":"..."}'

# Login and check auth
smithery auth login
smithery auth whoami

# Publish your MCP server
smithery mcp publish "https://my-server.com" -n myorg/my-server

# Publish an MCPB bundle
smithery mcp publish ./server.mcpb -n myorg/my-server

# Show help
smithery --help
```

--------------------------------

### Constraint Logic Examples

Source: https://smithery.ai/docs/use/token-scoping

Examples demonstrating how adding fields narrows access and adding to lists widens access.

```typescript
// Adding fields narrows the grant
{ resources: 'connections' }
// → any operation on connections

{ resources: 'connections', operations: 'read' }
// → only read connections

{ resources: 'connections', operations: 'read', metadata: { userId: 'user-123' } }
// → only read user-123's connections

// Adding to a list widens the grant
{ operations: ['read', 'write'] }
// → read OR write

{ metadata: [{ userId: 'user-123' }, { workspaceId: 'ws-acme' }] }
// → userId=user-123 OR workspaceId=ws-acme
```

--------------------------------

### List connections API requests

Source: https://smithery.ai/docs/api-reference/connect

Examples of how to fetch connections using various programming languages and tools.

```curl
curl --request GET \
  --url https://api.smithery.ai/connect/{namespace} \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.smithery.ai/connect/{namespace}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.smithery.ai/connect/{namespace}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smithery.ai/connect/{namespace}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smithery.ai/connect/{namespace}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.smithery.ai/connect/{namespace}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.smithery.ai/connect/{namespace}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Install Smithery CLI

Source: https://smithery.ai/docs/concepts/cli

Install the latest version of the Smithery CLI globally using npm. Requires Node.js 20 or higher.

```bash
npm install -g smithery@latest
```

--------------------------------

### List Skills

Source: https://smithery.ai/docs/api-reference/skills/list-or-search-skills

This example demonstrates how to iterate through all available skills, fetching additional pages automatically as needed.

```APIDOC
## List Skills

### Description
Retrieves a paginated list of skills. The client automatically fetches subsequent pages as you iterate through the results.

### Method
GET

### Endpoint
/skills

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of skills to return per page.
- **offset** (integer) - Optional - The number of skills to skip before starting to collect the result set.

### Response
#### Success Response (200)
- **skills** (array) - An array of SkillSummary objects.
- **pagination** (object) - Pagination details for the response.
  - **currentPage** (integer) - Current page number (1-indexed).
  - **pageSize** (integer) - Number of results per page.
  - **totalPages** (integer) - Total number of pages available.
  - **totalCount** (integer) - Total number of matching skills.

#### Response Example
```json
{
  "skills": [
    {
      "id": "skill-id-1",
      "namespace": "example-namespace",
      "slug": "example-skill",
      "displayName": "Example Skill",
      "description": "A sample skill.",
      "prompt": "What is the capital of France?",
      "qualityScore": 0.9,
      "externalStars": 100,
      "externalForks": 20,
      "totalActivations": 5000,
      "uniqueUsers": 1000,
      "categories": ["example", "sample"],
      "servers": ["mcp-server-1"],
      "gitUrl": "https://github.com/example/skill",
      "verified": true,
      "listed": true,
      "createdAt": "2023-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalCount": 50
  }
}
```

### Client-side Code Example (JavaScript)
```javascript
// Automatically fetches more pages as needed.
for await (const skillListResponse of client.skills.list()) {
  console.log(skillListResponse.id);
}
```
```

--------------------------------

### Quick Start with MCP Client

Source: https://smithery.ai/docs/integrations/vercel_ai_sdk

Initialize an MCP client using a Smithery connection and generate text with AI SDK tools.

```typescript
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();
```

--------------------------------

### Install Dependencies for Next.js MCP Client

Source: https://smithery.ai/docs/cookbooks/typescript_oauth_client

Installs the necessary dependencies for a Next.js project to function as an MCP client. This includes creating a new Next.js app and installing the MCP TypeScript SDK.

```bash
npx create-next-app@latest my-mcp-client
cd my-mcp-client
npm install @modelcontextprotocol/sdk
```

--------------------------------

### Example Usage of Release ID

Source: https://smithery.ai/docs/api-reference/servers/get-a-release

Demonstrates accessing the ID of a release object. This is a basic example of how release data might be accessed.

```javascript
console.log(release.id);
```

--------------------------------

### Call tools via CLI and TypeScript

Source: https://smithery.ai/docs/use/connect

Use these examples to list available tools and execute specific tool functions through the CLI or the MCP client.

```bash
# List available tools
smithery tool list user-123-github

# Call a tool
smithery tool call user-123-github search_repositories \
  '{"query": "mcp"}'
```

```typescript
const { transport } = await createConnection({
  client: smithery,
  namespace: 'my-app',
  connectionId: 'user-123-github',
})

const mcpClient = await createMCPClient({ transport })
const tools = await mcpClient.tools()
const result = await mcpClient.callTool({
  name: 'search_repositories',
  arguments: { query: 'mcp' },
})
await mcpClient.close()
```

--------------------------------

### List User Namespaces

Source: https://smithery.ai/docs/api-reference/namespaces/get-users-namespaces-or-search-namespaces

Iterate through all namespaces associated with the authenticated user. This example logs the name of each namespace found.

```javascript
for await (const namespaceListResponse of client.namespaces.list())
            {
              console.log(namespaceListResponse.name);
            }
```

--------------------------------

### Retrieve server details by qualified name

Source: https://smithery.ai/docs/api-reference/servers

Examples for fetching server information using various programming languages and HTTP clients.

```javascript
import Smithery from '@smithery/api';

const client = new Smithery({
  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted
});

const server = await client.servers.get('qualifiedName');

console.log(server.connections);
```

```bash
curl --request GET \
  --url https://api.smithery.ai/servers/{qualifiedName} \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.smithery.ai/servers/{qualifiedName}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smithery.ai/servers/{qualifiedName}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smithery.ai/servers/{qualifiedName}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.smithery.ai/servers/{qualifiedName}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.smithery.ai/servers/{qualifiedName}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### List skills using various programming languages

Source: https://smithery.ai/docs/api-reference/skills

Examples of how to authenticate and retrieve a list of skills using different HTTP clients and SDKs.

```javascript
import Smithery from '@smithery/api';

const client = new Smithery({
  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const skillListResponse of client.skills.list()) {
  console.log(skillListResponse.id);
}
```

```curl
curl --request GET \
  --url https://api.smithery.ai/skills \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.smithery.ai/skills"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smithery.ai/skills",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smithery.ai/skills"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.smithery.ai/skills")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.smithery.ai/skills")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Handle OAuth Authorization

Source: https://smithery.ai/docs/use/connect

Initiate a connection and handle the auth_required state to obtain a setup URL for user authorization.

```bash
# Connect to a server that requires OAuth
smithery mcp add github

# If auth is required, the CLI outputs the setup URL:
# → auth_required
# → https://auth.smithery.ai/...
# → connection_id: abc-123-github
# Visit the URL to authorize, then retry
```

```typescript
const conn = await smithery.connections.set('abc-123-github', {
  namespace: 'my-app',
  mcpUrl: 'https://github.run.tools',
});

if (conn.status?.state === 'auth_required') {
  redirect(conn.status.setupUrl);
}

// Save conn.connectionId and retry with it after the user returns
```

--------------------------------

### List Namespaces API Requests

Source: https://smithery.ai/docs/api-reference/namespaces

Examples of how to retrieve a list of namespaces using various programming languages and tools.

```javascript
import Smithery from '@smithery/api';

const client = new Smithery({
  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const namespaceListResponse of client.namespaces.list()) {
  console.log(namespaceListResponse.name);
}
```

```bash
curl --request GET \
  --url https://api.smithery.ai/namespaces \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.smithery.ai/namespaces"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smithery.ai/namespaces",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smithery.ai/namespaces"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.smithery.ai/namespaces")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.smithery.ai/namespaces")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### GET /connect/{namespace}

Source: https://smithery.ai/docs/api-reference/connect

Retrieves a list of connections for the specified namespace.

```APIDOC
## GET /connect/{namespace}

### Description
Retrieves a list of connections for the specified namespace.

### Method
GET

### Endpoint
https://api.smithery.ai/connect/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace identifier for the connections.

### Response
#### Success Response (200)
- **connections** (object[]) - List of connections
- **nextCursor** (string | null) - Cursor for next page, null if no more results

#### Response Example
{
  "connections": [
    {
      "connectionId": "clever-dolphin-a9X3",
      "name": "<string>",
      "mcpUrl": "<string>",
      "metadata": {},
      "transport": "http",
      "mock": {
        "enabled": true,
        "scenario": "Slack workspace with an active #community-ops channel containing recent event-planning messages, plus 50 Airtable candidate records with mixed tenure and interests."
      },
      "iconUrl": "<string>",
      "createdAt": "<string>",
      "status": {
        "state": "connected"
      },
      "serverInfo": {
        "name": "<string>",
        "version": "<string>",
        "title": "<string>",
        "icons": [
          {
            "src": "<string>",
            "mimeType": "<string>",
            "sizes": [
              "<string>"
            ],
            "theme": "light"
          }
        ],
        "websiteUrl": "<string>",
        "description": "<string>"
      }
    }
  ],
  "nextCursor": "<string>"
}
```

--------------------------------

### Manage Tools with Smithery CLI

Source: https://smithery.ai/docs/concepts/cli

List, find, get details for, and call tools from connected MCP servers.

```bash
# List tools from your connected MCP servers
smithery tool list

# Call a tool
smithery tool call exa search '{"query": "latest news about MCP"}'
```

--------------------------------

### Create Token with Multiple Grants

Source: https://smithery.ai/docs/use/token-scoping

Examples of creating a token with multiple independent grants using CLI, TypeScript, and cURL.

```bash
# Two grants: read alice's connections OR read/write servers
smithery auth token --policy '[
  {
    "resources": "connections",
    "operations": "read",
    "metadata": { "owner": "alice" }
  },
  {
    "resources": "servers",
    "operations": ["read", "write"]
  }
]'
```

```typescript
// Two grants: read alice's connections OR read/write servers
const { token } = await smithery.tokens.create({
  policy: [
    {
      resources: 'connections',
      operations: 'read',
      metadata: { owner: 'alice' },
    },
    {
      resources: 'servers',
      operations: ['read', 'write'],
    },
  ],
})
```

```bash
# Two grants: read alice's connections OR read/write servers
curl -X POST https://api.smithery.ai/tokens \
  -H "Authorization: Bearer $SMITHERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": [
      {
        "resources": "connections",
        "operations": "read",
        "metadata": { "owner": "alice" }
      },
      {
        "resources": "servers",
        "operations": ["read", "write"]
      }
    ]
  }'
```

--------------------------------

### Example Event POST Request

Source: https://smithery.ai/docs/use/triggers

The structure of an incoming event POST request sent to the configured delivery URL.

```http
POST https://my-app.example.com/events
Content-Type: application/json
webhook-id: evt_01HW...
webhook-timestamp: 1739980800
webhook-signature: v1,<base64 HMAC-SHA256(secret, "id.timestamp.body")>
X-MCP-Subscription-Id: sub_a3f1c8e2b0d49f7e

{
  "eventId": "evt_01HW...",
  "name": "page.updated",
  "timestamp": "2026-04-22T12:00:00.000Z",
  "data": {
    "page_id": "...",
    "updated_at": "2026-04-22T12:00:00.000Z"
  }
}
```

--------------------------------

### Basic Smithery CLI Commands

Source: https://smithery.ai/docs/concepts/cli

Common commands to get help, authenticate, search for MCP servers, and add them locally or remotely.

```bash
# Show the help menu
smithery --help

# Authenticate with Smithery
smithery auth login

# Search for MCP servers
smithery mcp search "github"

# Add an MCP server to a local client (e.g., Claude Desktop)
smithery mcp add exa --client claude

# Add an MCP server as a remote Smithery connection
smithery mcp add https://server.smithery.ai/exa --id exa
```

--------------------------------

### Configure Multi-Level Access Tokens

Source: https://smithery.ai/docs/use/token-scoping

Examples of defining multiple policy grants to allow access to user-specific, workspace-shared, and global resources.

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

```typescript
const { token } = await smithery.tokens.create({
  policy: [
    // Grant 1: user's own connections
    {
      namespaces: 'my-app',
      resources: 'connections',
      operations: ['read', 'execute'],
      metadata: { userId: 'user-123' },
      ttl: '1h',
    },
    // Grant 2: workspace-shared connections
    {
      namespaces: 'my-app',
      resources: 'connections',
      operations: ['read', 'execute'],
      metadata: { workspaceId: 'ws-acme' },
      ttl: '1h',
    },
    // Grant 3: global connections (admin-configured)
    {
      namespaces: 'my-app',
      resources: 'connections',
      operations: ['read', 'execute'],
      metadata: { scope: 'global' },
      ttl: '1h',
    },
  ],
})
```

```bash
curl -X POST https://api.smithery.ai/tokens \
  -H "Authorization: Bearer $SMITHERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": [
      {
        "namespaces": "my-app",
        "resources": "connections",
        "operations": ["read", "execute"],
        "metadata": { "userId": "user-123" },
        "ttl": "1h"
      },
      {
        "namespaces": "my-app",
        "resources": "connections",
        "operations": ["read", "execute"],
        "metadata": { "workspaceId": "ws-acme" },
        "ttl": "1h"
      },
      {
        "namespaces": "my-app",
        "resources": "connections",
        "operations": ["read", "execute"],
        "metadata": { "scope": "global" },
        "ttl": "1h"
      }
    ]
  }'
```

--------------------------------

### Implement PostHog API Key configuration

Source: https://smithery.ai/docs/build/session-config

Example schema mapping a client-provided header to an Authorization header for an upstream service.

```typescript
export const configSchema = z.object({
  posthogApiKey: z.string()
    .meta({
      "x-from": { header: "posthog-api-key" },  // Client provides this header
      "x-to": { header: "Authorization" }       // PostHog expects Authorization
    })
    .describe("Your PostHog API key"),
});
```

--------------------------------

### GET /connect/{namespace}

Source: https://smithery.ai/docs/api-reference/connect

List all connections in a namespace. Supports filtering by metadata using metadata.{key}={value} query params.

```APIDOC
## GET /connect/{namespace}

### Description
List all connections in a namespace. Supports filtering by metadata using `metadata.{key}={value}` query params.

### Method
GET

### Endpoint
/connect/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace identifier.

#### Query Parameters
- **limit** (integer) - Optional - Maximum number of items to return (default 100, max 100).
- **cursor** (string) - Optional - Pagination cursor from previous response's nextCursor.
- **name** (string) - Optional - Filter by exact connection name.
- **mcpUrl** (string) - Optional - Filter by exact MCP server URL.

### Response
#### Success Response (200)
- **connections** (array) - List of connection objects.
- **nextCursor** (string) - Pagination cursor for the next page.

#### Response Example
{
  "connections": [
    {
      "connectionId": "clever-dolphin-a9X3",
      "name": "<string>",
      "mcpUrl": "<string>",
      "metadata": {},
      "transport": "http",
      "mock": {
        "enabled": true,
        "scenario": "Slack workspace with an active #community-ops channel containing recent event-planning messages, plus 50 Airtable candidate records with mixed tenure and interests."
      },
      "iconUrl": "<string>",
      "createdAt": "<string>",
      "status": {
        "state": "connected"
      },
      "serverInfo": {
        "name": "<string>",
        "version": "<string>",
        "title": "<string>",
        "icons": [
          {
            "src": "<string>",
            "mimeType": "<string>",
            "sizes": [
              "<string>"
            ],
            "theme": "light"
          }
        ],
        "websiteUrl": "<string>",
        "description": "<string>"
      }
    }
  ],
  "nextCursor": "<string>"
}
```

--------------------------------

### Connect to an MCP server using TypeScript

Source: https://smithery.ai/docs/use/connect

Establish a connection and retrieve a transport using the Smithery SDK. Configuration is passed during the connection setup.

```typescript
import Smithery from '@smithery/api';
import { createConnection } from '@smithery/api/mcp';

const smithery = new Smithery();

// 1. Create a connection with the server's config
//    - API keys go in `headers`
//    - Other config goes as query params in `mcpUrl`
const conn = await smithery.connections.set('my-browserbase', {
  namespace: 'my-app',
  mcpUrl: 'https://mcp.browserbase.com/mcp?browserbaseProjectId=your-project-id',
  headers: {
    'browserbaseApiKey': 'your-browserbase-api-key',
  },
});
// conn.status.state === "connected" — ready to use immediately

// 2. Get a transport for the connection
const { transport } = await createConnection({
  client: smithery,
  namespace: 'my-app',
  connectionId: conn.connectionId,
});
```

--------------------------------

### Get Release Details (JavaScript)

Source: https://smithery.ai/docs/api-reference/servers/get-a-release

Use this JavaScript snippet to fetch release information by providing the release ID and the server's qualified name. Ensure you have the Smithery SDK installed and your API key configured.

```javascript
import Smithery from '@smithery/api';


const client = new Smithery({
  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted
});


const release = await client.servers.releases.get('id', {
  qualifiedName: 'qualifiedName'
});
```

--------------------------------

### Get Server Icon using JavaScript

Source: https://smithery.ai/docs/api-reference/servers/get-server-icon

Use this snippet to retrieve a server's icon. Ensure you have the Smithery API client installed and your API key configured. The icon is returned directly, and you can access its content as a blob.

```JavaScript
import Smithery from '@smithery/api';

const client = new Smithery({
  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted
});

const icon = await client.servers.icon.get('qualifiedName');

console.log(icon);

const content = await icon.blob();
console.log(content);
```

--------------------------------

### Add an MCP server with configuration

Source: https://smithery.ai/docs/use/connect

Use the Smithery CLI to register a server, passing configuration via headers and query parameters.

```bash
# Add a server with config (API key as header, project ID as query param)
smithery mcp add \
  '@browserbasehq/mcp-browserbase?browserbaseProjectId=your-project-id' \
  --id my-browserbase \
  --headers '{"browserbaseApiKey": "your-browserbase-api-key"}'
```

--------------------------------

### OpenAPI Specification for Get Tool

Source: https://smithery.ai/docs/api-reference/connect/get-tool

This OpenAPI 3.1.0 specification defines the GET endpoint for retrieving tool information. It includes parameters for namespace, connection ID, and tool path, along with response schemas for successful retrieval (Tool or ToolList) and errors.

```yaml
openapi: 3.1.0
info:
  title: Smithery Platform API
  description: >-
    API for the Smithery platform — discover, deploy, and manage MCP (Model
    Context Protocol) servers. Provides endpoints for browsing the server
    registry, managing deployments, creating scoped access tokens, and
    connecting to MCP servers.
  version: 1.0.0
servers:
  - url: https://api.smithery.ai
security:
  - bearerAuth: []
tags:
  - name: servers
    description: >-
      Browse the MCP server registry, manage server configuration, and handle
      deployments
  - name: skills
    description: Discover and search reusable prompt-based skills for MCP servers
  - name: tools
    description: Search for MCP tools across all registered servers
paths:
  /connect/{namespace}/{connectionId}/.tools/{toolPath}:
    get:
      tags:
        - connect
      summary: Get tool
      description: Get one tool or list tools under a slash-separated category.
      operationId: getSmithery.run:namespace:connectionId.tools:toolPath
      parameters:
        - schema:
            type: string
          in: path
          name: namespace
          required: true
        - schema:
            type: string
          in: path
          name: connectionId
          required: true
        - schema:
            type: string
          in: path
          name: toolPath
          required: true
      responses:
        '200':
          description: Tool metadata or category listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
        '404':
          description: Connection or tool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ToolResponse:
      anyOf:
        - $ref: '#/components/schemas/Tool'
        - $ref: '#/components/schemas/ToolList'
    Error:
      type: object
      properties:
        error:
          type: string
          example: not_found
        message:
          type: string
          example: Resource not found
      required:
        - error
        - message
      additionalProperties: false
    Tool:
      type: object
      properties:
        name:
          type: string
        title:
          type: string
        icons:
          type: array
          items:
            type: object
            properties:
              src:
                type: string
              mimeType:
                type: string
              sizes:
                type: array
                items:
                  type: string
              theme:
                type: string
                enum:
                  - light
                  - dark
            required:
              - src
            additionalProperties: false
        description:
          type: string
        inputSchema:
          type: object
          properties:
            type:
              type: string
              const: object
            properties:
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
            required:
              type: array
              items:
                type: string
          required:
            - type
          additionalProperties: {}
        outputSchema:
          type: object
          properties:
            type:
              type: string
              const: object
            properties:
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
            required:
              type: array
              items:
                type: string
          required:
            - type
          additionalProperties: {}
        annotations:
          type: object
          properties:
            title:
              type: string
            readOnlyHint:
              type: boolean
            destructiveHint:
              type: boolean
            idempotentHint:
              type: boolean
            openWorldHint:
              type: boolean
          additionalProperties: false
        execution:
          type: object
          properties:
            taskSupport:
              type: string
              enum:
                - required
                - optional
                - forbidden
          additionalProperties: false
        _meta:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - name

```

--------------------------------

### GET /namespaces

Source: https://smithery.ai/docs/api-reference/namespaces

Retrieves a list of namespaces with pagination details.

```APIDOC
## GET /namespaces

### Description
Retrieves a paginated list of namespaces available in the system.

### Method
GET

### Endpoint
https://api.smithery.ai/namespaces

### Response
#### Success Response (200)
- **namespaces** (array) - List of namespace objects
- **pagination** (object) - Pagination metadata

#### Response Example
{
  "namespaces": [
    {
      "name": "anthropic"
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 0,
    "totalPages": 0,
    "totalCount": 0
  }
}
```

--------------------------------

### Pass configuration via CLI arguments

Source: https://smithery.ai/docs/build/session-config

Local servers receive configuration as kebab-case flags derived from the schema field names.

```bash
my-server --api-key=sk-xxx --model=gpt-4 --temperature=0.7
```

--------------------------------

### GET /skills

Source: https://smithery.ai/docs/api-reference/skills

Retrieves a paginated list of skills available in the system.

```APIDOC
## GET /skills

### Description
Retrieves a paginated list of skills available in the system.

### Method
GET

### Endpoint
https://api.smithery.ai/skills

### Response
#### Success Response (200)
- **skills** (object[]) - List of skill objects
- **pagination** (object) - Pagination metadata

#### Response Example
{
  "skills": [
    {
      "id": "<string>",
      "namespace": "<string>",
      "slug": "<string>",
      "displayName": "<string>",
      "description": "<string>",
      "prompt": "<string>",
      "qualityScore": 123,
      "verified": true,
      "listed": true,
      "createdAt": "<string>",
      "externalStars": 123,
      "externalForks": 123,
      "totalActivations": 123,
      "uniqueUsers": 123,
      "categories": ["<string>"],
      "servers": ["<string>"],
      "gitUrl": "<string>"
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 0,
    "totalPages": 0,
    "totalCount": 0
  }
}
```

--------------------------------

### Download Server Bundle using JavaScript

Source: https://smithery.ai/docs/api-reference/servers/download-server-bundle

Use this snippet to download the MCPB bundle for the latest successful stdio release. Ensure you have your SMITHERY_API_KEY set as an environment variable. The response contains the bundle as a blob.

```javascript
import Smithery from '@smithery/api';

const client = new Smithery({
  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted
});

const response = await client.servers.download('qualifiedName');

console.log(response);

const content = await response.blob();
console.log(content);
```

--------------------------------

### Publish URL-based Server via CLI

Source: https://smithery.ai/docs/build/publish

Commands for publishing a server URL to Smithery, optionally including a configuration schema.

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

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

--------------------------------

### Get a Skill by Namespace and Slug

Source: https://smithery.ai/docs/api-reference/skills/get-a-skill

Fetches a single skill by its namespace and slug.

```APIDOC
## GET /skills/{namespace}/{slug}

### Description
Get a single skill by its namespace and slug.

### Method
GET

### Endpoint
/skills/{namespace}/{slug}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace of the skill.
- **slug** (string) - Required - The slug of the skill.

### Responses
#### Success Response (200)
- **id** (string)
- **namespace** (string)
- **slug** (string)
- **displayName** (string)
- **description** (string)
- **prompt** (string)
- **qualityScore** (number)
- **externalStars** (number)
- **externalForks** (number)
- **totalActivations** (number)
- **uniqueUsers** (number)
- **categories** (array of strings)
- **servers** (array of strings)
- **gitUrl** (string or null)
- **verified** (boolean) - Whether this skill's namespace is verified.
- **listed** (boolean)
- **owner** (string or null) - Organization ID of the skill owner (from namespace).
- **createdAt** (string)

#### Response Example (200)
{
  "id": "clt8j3f1a000008l4g8h4j4j4",
  "namespace": "example-namespace",
  "slug": "example-skill",
  "displayName": "Example Skill",
  "description": "An example skill for demonstration purposes.",
  "prompt": "What is the capital of France?",
  "qualityScore": 0.9,
  "externalStars": 100,
  "externalForks": 20,
  "totalActivations": 10000,
  "uniqueUsers": 5000,
  "categories": ["example", "demo"],
  "servers": ["mcp-server-1"],
  "gitUrl": "https://github.com/example/example-skill.git",
  "verified": true,
  "listed": true,
  "owner": "org-123",
  "createdAt": "2023-01-01T12:00:00Z"
}

#### Error Response (404)
{
  "error": "Skill not found"
}
```

--------------------------------

### Get Release Details

Source: https://smithery.ai/docs/api-reference/servers/get-a-release

Fetches the details of a specific release using its ID.

```APIDOC
## GET /servers/{server_id}/releases/{release_id}

### Description
Retrieves details for a specific release.

### Method
GET

### Endpoint
/servers/{server_id}/releases/{release_id}

### Parameters
#### Path Parameters
- **server_id** (string) - Required - The unique identifier for the server.
- **release_id** (string) - Required - The unique identifier for the release.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the release.
- **status** (string) - Current status: QUEUED, WORKING, SUCCESS, FAILURE, FAILURE_SCAN, AUTH_REQUIRED, AUTH_TIMEOUT, CANCELLED, or INTERNAL_ERROR.
- **type** (string) - Release type: hosted_shttp (Smithery-hosted), external_shttp (external URL), or stdio (local binary).
- **commit** (string or null) - Git commit SHA that triggered this release.
- **commitMessage** (string or null) - Git commit message associated with this release.
- **branch** (string or null) - Git branch this release was built from.
- **upstreamUrl** (string or null) - Upstream MCP server URL. Present only for external releases.
- **logs** (array) - Pipeline log entries. Only included when fetching a single release.
  - **stage** (string) - Pipeline stage: deploy, scan, metadata, publish.
  - **level** (string) - Log level: 'start', 'end', 'info', 'success', or 'failure'.
  - **message** (string) - Human-readable log message.
  - **timestamp** (string) - ISO 8601 timestamp of the log entry.
  - **error** (object or null) - Error details, present only when the stage failed.
    - **message** (string) - Error message.
- **mcpUrl** (string) - The MCP endpoint URL for connecting to this server.
- **createdAt** (string) - ISO 8601 timestamp of when the release was created.
- **updatedAt** (string) - ISO 8601 timestamp of the last status change.

#### Response Example
```json
{
  "id": "018a81a4-1234-4b7a-8c1d-0a1b2c3d4e5f",
  "status": "SUCCESS",
  "type": "hosted_shttp",
  "commit": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "commitMessage": "feat: Add new feature",
  "branch": "main",
  "upstreamUrl": null,
  "logs": [
    {
      "stage": "deploy",
      "level": "info",
      "message": "Uploading bundle...",
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "stage": "deploy",
      "level": "success",
      "message": "Bundle uploaded successfully.",
      "timestamp": "2023-10-27T10:01:00Z"
    }
  ],
  "mcpUrl": "https://mcp.example.com/servers/018a81a4-1234-4b7a-8c1d-0a1b2c3d4e5f",
  "createdAt": "2023-10-27T09:59:00Z",
  "updatedAt": "2023-10-27T10:01:00Z"
}
```
```

--------------------------------

### Download server bundle

Source: https://smithery.ai/docs/api-reference/servers/download-server-bundle

Download the MCPB bundle for the latest successful stdio release.

```APIDOC
## GET /servers/{qualifiedName}/download

### Description
Download the MCPB bundle for the latest successful stdio release.

### Method
GET

### Endpoint
/servers/{qualifiedName}/download

### Parameters
#### Path Parameters
- **qualifiedName** (string) - Required - The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.

### Responses
#### Success Response (200)
- **binary** (application/zip) - Bundle file

#### Error Response (404)
- **error** (string) - Bundle not found
```
Tokens:
Raw