Clients

The Hostsmith MCP server is published as @hostsmith/mcp-server on npm and hosted at https://mcp.hostsmith.net/mcp. Every supported client uses one of four transports.

Claude (claude.ai, Desktop, Cowork, mobile)

Add Hostsmith once as a custom connector and it works in every Claude app on your account.

1. In Claude, open Customize > Connectors, click + Add, then Add custom connector.
2. Enter Hostsmith as the name and paste the MCP server URL:

   https://mcp.hostsmith.net/mcp
   

3. Click Continue, finish adding the connector, then connect it. Claude opens Hostsmith in your browser to authorize the connector against your Hostsmith account.

Free Claude plans allow one custom connector. On Team and Enterprise plans, an owner adds the connector under Organization settings > Connectors, and each member then clicks Connect next to Hostsmith under Customize > Connectors to sign in with their own Hostsmith account.

Claude asks for your approval before each tool call. To change that, open Hostsmith under Customize > Connectors and set its Tool permissions.

To revoke, open Hostsmith under Customize > Connectors, click ⋯, then Remove (Team and Enterprise owners: Organization settings > Connectors). To force a re-auth, click Disconnect, then Connect.

Stdio (Claude Code, Cursor, Cline, Windsurf, Zed)

Add this entry to your client's MCP config:

{
  "mcpServers": {
    "hostsmith": {
      "command": "npx",
      "args": ["-y", "@hostsmith/mcp-server"]
    }
  }
}

Config file locations:

The first tool call triggers an OAuth flow in your browser to authorize the server against your Hostsmith account. The token is cached locally; subsequent calls reuse it.

Remote URL (other Streamable-HTTP clients)

Any MCP client that supports remote Streamable HTTP transport can point directly at the hosted server:

{
  "mcpServers": {
    "hostsmith": {
      "url": "https://mcp.hostsmith.net/mcp"
    }
  }
}

The client handles the OAuth flow automatically - you'll be redirected to Hostsmith to authorize access.

Claude Code can use the hosted server directly too:

claude mcp add --transport http hostsmith https://mcp.hostsmith.net/mcp

Local HTTP (self-hosted)

Run the server in HTTP mode locally and have your MCP client perform OAuth against it:

npx @hostsmith/mcp-server http

{
  "mcpServers": {
    "hostsmith": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

Useful when you want to inspect MCP traffic locally or pin to a specific server version. Set MCP_BASE_URL to override the public URL the server advertises in OAuth metadata. See the README for the full env var list.

Troubleshooting

• Tool calls return 401. The OAuth session expired. Reconnect from your client to re-authorize.
• OAuth redirect loops (self-hosted only). Confirm MCP_BASE_URL matches the URL your MCP client uses to reach the server.
• Wrong partition. Tool calls accept an explicit partition argument; if you omit it, the partition is inferred from your access token. See Authentication.
• Inspect tools interactively. Run npx @modelcontextprotocol/inspector npx -y @hostsmith/mcp-server http to browse the tool surface in a local UI.
• Stale npm cache. If you keep getting an old version, run npx clear-npx-cache or npm cache clean --force and try again.