# Connect Claude Desktop, Code, .ai, Mobile to ToolMesh

> Step-by-step setup for Claude Desktop, Claude Code, Claude.ai, and Claude Mobile against a ToolMesh MCP endpoint, with config.json and CLI examples.

Canonical: https://www.toolmesh.io/en/setup-claude/

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:

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

For local development without TLS:

```json
{
  "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](/en/getting-started/#tls-important) 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:

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

For local development:

```bash
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:

```bash
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:

```json
{
  "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](/en/getting-started/) — install ToolMesh and configure authentication
- [Authentication](/en/authentication/) — OAuth 2.1, API keys, and multi-user setup
- [Configuration](/en/configuration/) — all environment variables and config file reference