MCP Server (Claude Desktop)

The osmTalk MCP server exposes your osmTalk agents as tools inside Claude Desktop, letting you list agents, trigger outbound calls, and check call status without leaving your AI assistant.

What It Does

The MCP server provides Claude Desktop with a set of tools backed by the osmTalk API:

Example conversations

• "List the healthcare templates" → invokes list_templates(category='healthcare')
• "What's the cheapest preset right now?" → invokes get_presets, returns the Fast tier with the live cost range
• "Is OpenAI healthy?" → invokes get_model_health and reads back the status badge
• "Find a template for a pizza-ordering agent" → invokes list_templates(q='order')

Requirements

• Claude Desktop installed (or any MCP-compatible client)
• An osmTalk API key with the right scopes (Settings → API Keys)
• Node.js 18+ for npx

Installation

The server ships on npm. No global install needed — Claude Desktop spawns it via npx on demand.

# Optional: pre-warm the package cache
npx -y @osmapi/mcp-server-osmtalk --help

Configuration

Add the server to your client's MCP config file.

Locations of claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "osmtalk": {
      "command": "npx",
      "args": ["-y", "@osmapi/mcp-server-osmtalk"],
      "env": {
        "OSMTALK_API_KEY": "osm_your_api_key_here",
        "OSMTALK_API_URL": "https://api.osmtalk.com"
      }
    }
  }
}

Restart Claude Desktop after editing the config — MCP servers are loaded once at startup.

Required API key scopes

The MCP server uses the widget-style API key (the same one that powers /api/widget/* routes). Grant only what you need:

Usage

After restarting Claude Desktop, the osmTalk tools appear automatically. Invoke them conversationally:

• "List my osmTalk agents"
• "Call +15551234567 using my support agent and ask them to confirm Tuesday's appointment"
• "Find a healthcare template and create an agent from it"
• "What's the cheapest quality preset right now?"
• "Is OpenAI healthy? If not, recommend a backup model"

Claude decides when to use which tool based on your message, the same way any MCP integration works.

Verifying the connection

After config + restart, ask Claude "Use the osmtalk MCP server to list my agents". If you see your agents, the server is wired correctly.

If it fails:

• "OSMTALK_API_KEY environment variable is required" — env block is missing from the config or has a typo in the key name. Restart Claude Desktop after fixing.
• HTTP 401 / "Invalid API key" — key was revoked or doesn't exist. Create a new one in Settings → API Keys.
• HTTP 403 / "Origin not allowed" — your API key has an allowed-domains restriction. Either remove the restriction (it doesn't make sense for an MCP server) or use a separate key without it.
• Empty tool list in Claude — open Claude Desktop's MCP log: macOS View → Logs → Open Console; look for osmtalk entries.

Self-hosted deployments

Point OSMTALK_API_URL at your API host. The MCP server uses the same widget-style endpoints (/api/widget/*) so it works with any osmTalk deployment that has the widget routes enabled (the default).

If you're behind a VPN-only API host, set the env var to the internal hostname Claude Desktop can reach.

API Key

Create a dedicated key for the MCP server under Settings → API Keys. Assign only the scopes listed above. See API Keys for setup instructions.