Connect Claude to ToolMesh

Every Claude product supports MCP, but the setup differs between the web interface, desktop app, CLI, and mobile. This guide covers connecting each to your ToolMesh instance.

Claude Desktop

Claude Desktop supports both local and remote MCP servers via a JSON config file.

Config file location

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Open Claude Desktop, click the Claude menu, then Settings > Developer > Edit Config.

Add ToolMesh as a remote server

Add the following to your config file:

{
  "mcpServers": {
    "toolmesh": {
      "url": "https://toolmesh.example.com/mcp"
    }
  }
}

For local development without TLS:

{
  "mcpServers": {
    "toolmesh": {
      "url": "http://localhost:8123/mcp"
    }
  }
}

Verify the connection

Fully quit and relaunch Claude Desktop after editing the config (Cmd+Q on macOS, right-click system tray > Exit on Windows). A hammer icon in the bottom-right of the chat input confirms the connection. Click it to see available ToolMesh tools.

Troubleshooting

Issue	Fix
Hammer icon missing	Check JSON syntax — trailing commas and mismatched brackets are common
Connection refused	Verify ToolMesh is running (curl http://localhost:8123/health)
HTTPS required	Claude Desktop’s GUI enforces https:// — use a TLS proxy or edit the config file directly for local http:// URLs

Log files: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\ (Windows).

---

Claude Code

Claude Code connects via CLI and supports API key authentication natively.

Quick setup

Set TOOLMESH_API_KEY in your ToolMesh .env file, then add the server:

claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" -s user toolmesh https://toolmesh.example.com/mcp

For local development:

claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" -s user toolmesh http://localhost:8123/mcp

Scope levels

Claude Code stores MCP config at three levels:

Scope	Flag	Stored in	Shared with team
Local (default)	—	~/.claude.json	No
Project	--scope project	.mcp.json in repo root	Yes (committed to git)
User	--scope user	~/.claude.json (global)	No

To share the ToolMesh connection with your team, use project scope:

claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" --scope project toolmesh https://toolmesh.example.com/mcp

This creates a .mcp.json file at the repo root:

{
  "mcpServers": {
    "toolmesh": {
      "type": "http",
      "url": "https://toolmesh.example.com/mcp"
    }
  }
}

Useful commands

Command	Purpose
claude mcp list	List all configured servers
claude mcp get toolmesh	View ToolMesh connection details
claude mcp remove toolmesh	Remove the connection
/mcp (in-session)	Check status, restart, or re-authenticate
claude --mcp-debug	Verbose connection logging at startup

---

Claude.ai

The web interface supports remote MCP servers only through the Connectors panel.

Setup

1. Go to Settings > Connectors (https://claude.ai/settings/connectors)
2. Scroll down and click Add custom connector
3. Enter your ToolMesh HTTPS URL (e.g. https://toolmesh.example.com/mcp)
4. If using OAuth, expand Advanced settings and enter the OAuth Client ID and Secret
5. Click Add

Enable in a conversation

Click the + button in the chat input, select Connectors, and toggle ToolMesh on. When Claude uses a tool, you can approve with “Allow once” or “Allow always”.

Authentication

ToolMesh supports OAuth 2.1 with PKCE S256, which Claude.ai uses for remote connections. Configure users in config/users.yaml on the ToolMesh side. The OAuth callback URL is https://claude.ai/api/mcp/auth_callback.

Plan limits

Free plan users are limited to one custom connector. Paid plans (Pro, Max, Team, Enterprise) have no stated limit.

Team and Enterprise

Organization Owners must first add ToolMesh at the org level through Organization settings > Connectors. Team members then connect individually from their personal Settings > Connectors page.

---

Claude Mobile

Claude for iOS and Android can use MCP servers that were previously configured via claude.ai. There is no way to add new servers directly from the mobile app. Once ToolMesh is connected in claude.ai, it becomes available on mobile automatically.

---

Next steps

• Getting Started — install ToolMesh and configure authentication
• Authentication — OAuth 2.1, API keys, and multi-user setup
• Configuration — all environment variables and config file reference