> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mokaru.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect MCP clients

> Step-by-step setup for Claude, Cursor, Gemini, OpenClaw, and other MCP-compatible AI agents

This page covers every common MCP client. Pick yours below.

<Note>
  **Server URL** for all clients: `https://api.mokaru.ai/mcp`

  **Auth**: OAuth in browser, the first time you use a tool. **Requires a Plus plan.**
</Note>

## Claude.ai (web)

Anthropic's web app supports remote MCP servers via the Connectors feature.

<Steps>
  <Step title="Open settings">
    Go to [claude.ai/settings/connectors](https://claude.ai/settings/connectors).
  </Step>

  <Step title="Add a custom connector">
    Click **Add custom connector** at the bottom of the page.
  </Step>

  <Step title="Enter the Mokaru server URL">
    * **Name**: `Mokaru`
    * **Remote MCP server URL**: `https://api.mokaru.ai/mcp`

    Click **Add**.
  </Step>

  <Step title="Authorize">
    Claude opens a Mokaru sign-in page in a new tab. Sign in (or you're already signed in), click **Allow access**, and you're redirected back.
  </Step>

  <Step title="Use it">
    Start a new chat. Mokaru appears in the connectors picker. Try:

    > Search Mokaru for remote product manager jobs posted this week.
  </Step>
</Steps>

<Tip>
  Custom connectors require **Claude Pro, Max, Team, or Enterprise**. Free tier users see the Connectors page but cannot add custom servers.
</Tip>

## Claude Desktop

The native macOS/Windows app. Setup is via JSON config.

<Steps>
  <Step title="Open the config file">
    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux**: `~/.config/Claude/claude_desktop_config.json`

    Create it if it doesn't exist.
  </Step>

  <Step title="Add Mokaru">
    ```json theme={null}
    {
      "mcpServers": {
        "mokaru": {
          "url": "https://api.mokaru.ai/mcp"
        }
      }
    }
    ```

    If you already have other `mcpServers`, add `"mokaru"` alongside them.
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and reopen the app. Mokaru should appear in the tools picker (the little plug icon near the message input).
  </Step>

  <Step title="Authorize on first use">
    The first time Claude calls a Mokaru tool, your browser opens to sign in and approve. The token is then cached locally until it expires.
  </Step>
</Steps>

## Cursor

Cursor (the AI-first editor) has built-in MCP support.

<Steps>
  <Step title="Open MCP settings">
    **Cursor Settings → Features → MCP** (or `Cmd/Ctrl + Shift + J` then search "MCP").
  </Step>

  <Step title="Add a new server">
    Click **Add new MCP server**. Fill in:

    * **Name**: `Mokaru`
    * **Type**: `URL` (or `streamable-http` depending on Cursor version)
    * **URL**: `https://api.mokaru.ai/mcp`
  </Step>

  <Step title="Save and restart">
    Click **Save**. Restart Cursor.
  </Step>

  <Step title="Use in Cursor chat or Composer">
    In Cursor's chat panel, the Mokaru tools become available alongside Cursor's built-in coding tools. Try:

    > List my Mokaru job applications and their status.
  </Step>
</Steps>

## Claude Code (CLI)

Anthropic's command-line agent.

<Steps>
  <Step title="Add the server">
    ```bash theme={null}
    claude mcp add mokaru --transport http https://api.mokaru.ai/mcp
    ```

    This writes the config to `~/.claude.json`.
  </Step>

  <Step title="Authorize">
    Start a Claude Code session: `claude`. On the first Mokaru tool call, your browser opens for OAuth. Approve, return to the terminal.
  </Step>

  <Step title="Verify">
    Inside a session, type:

    ```
    /mcp
    ```

    You should see `mokaru` listed as connected.
  </Step>
</Steps>

## Gemini CLI

Google's command-line agent (npm package `@google/gemini-cli`).

<Steps>
  <Step title="Open the settings file">
    `~/.gemini/settings.json`. Create it if it doesn't exist.
  </Step>

  <Step title="Add Mokaru">
    ```json theme={null}
    {
      "mcpServers": {
        "mokaru": {
          "httpUrl": "https://api.mokaru.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Authorize on first run">
    Run `gemini` in your terminal. The first call to a Mokaru tool opens your browser for OAuth.
  </Step>
</Steps>

<Tip>
  Gemini Code Assist (the JetBrains / VS Code extension) reads the same `~/.gemini/settings.json` for agent mode, so the same config works in both.
</Tip>

## OpenClaw / ClawHub

Mokaru maintains an official skill on [ClawHub](https://clawhub.ai/VNDCK/auto-apply) - this is the easiest path if you use OpenClaw.

<Steps>
  <Step title="Install the Mokaru skill">
    Visit [clawhub.ai/VNDCK/auto-apply](https://clawhub.ai/VNDCK/auto-apply) and click **Install** to add it to your OpenClaw agent.
  </Step>

  <Step title="Or use raw MCP">
    If you want the full MCP toolset instead of the curated skill, add Mokaru as a custom MCP server in OpenClaw's settings:

    ```json theme={null}
    {
      "mcpServers": {
        "mokaru": {
          "url": "https://api.mokaru.ai/mcp"
        }
      }
    }
    ```
  </Step>
</Steps>

## Continue (VS Code / JetBrains)

Open-source AI assistant for editors.

<Steps>
  <Step title="Open config">
    Edit `~/.continue/config.yaml` (or `config.json` in older versions).
  </Step>

  <Step title="Add Mokaru">
    ```yaml theme={null}
    mcpServers:
      - name: Mokaru
        url: https://api.mokaru.ai/mcp
    ```
  </Step>

  <Step title="Reload">
    Reload the Continue extension. Mokaru's tools become available in agent mode.
  </Step>
</Steps>

## Zed

The Zed editor supports MCP via Context Servers.

<Steps>
  <Step title="Open settings">
    `Cmd + ,` (macOS) or `Ctrl + ,` (Linux) → opens `settings.json`.
  </Step>

  <Step title="Add Mokaru">
    ```json theme={null}
    {
      "context_servers": {
        "mokaru": {
          "source": "custom",
          "url": "https://api.mokaru.ai/mcp"
        }
      }
    }
    ```
  </Step>
</Steps>

## Custom MCP clients

Building your own agent? The MCP TypeScript and Python SDKs handle the full OAuth + transport flow when you point them at the Mokaru server URL.

<CodeGroup>
  ```ts TypeScript theme={null}
  import { Client } from '@modelcontextprotocol/sdk/client/index.js';
  import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

  const transport = new StreamableHTTPClientTransport(
    new URL('https://api.mokaru.ai/mcp')
  );

  const client = new Client({ name: 'my-agent', version: '1.0.0' });
  await client.connect(transport);

  const { tools } = await client.listTools();
  console.log(tools.map(t => t.name));

  const result = await client.callTool({
    name: 'mokaru_search_jobs',
    arguments: { query: 'product manager', location: 'Amsterdam' }
  });
  ```

  ```python Python theme={null}
  from mcp.client.streamable_http import streamablehttp_client
  from mcp import ClientSession

  async with streamablehttp_client("https://api.mokaru.ai/mcp") as (read, write, _):
      async with ClientSession(read, write) as session:
          await session.initialize()
          tools = await session.list_tools()
          print([t.name for t in tools.tools])

          result = await session.call_tool(
              "mokaru_search_jobs",
              {"query": "product manager", "location": "Amsterdam"},
          )
  ```
</CodeGroup>

Both SDKs auto-discover the OAuth endpoints, handle Dynamic Client Registration, run the browser flow, and refresh tokens. You don't need to implement any of it yourself - just provide the URL.

For the low-level OAuth wire protocol (if you're building an MCP client from scratch), see the [OAuth flow reference](/integrations/mcp-oauth).

## Troubleshooting

<AccordionGroup>
  <Accordion title="The browser opens but I see 'MCP requires Plus'">
    Your Mokaru account is on the Free plan. MCP integration requires Plus. [Upgrade](https://app.mokaru.ai/billing) and try again.
  </Accordion>

  <Accordion title="Authorization succeeds but tools fail with 'session expired'">
    Access tokens last 1 hour; refresh tokens last 30 days. If you haven't used the connection in over a month, the refresh chain is dead. Disconnect from Mokaru → Settings → MCP connections and re-authorize.
  </Accordion>

  <Accordion title="Claude Desktop / Cursor doesn't show Mokaru after adding the config">
    You need to fully quit and restart the app - reload-from-settings isn't enough for MCP servers. On macOS that means `Cmd + Q`, not just closing the window.
  </Accordion>

  <Accordion title="Multiple devices, do I need to authorize each one?">
    Yes - each MCP client instance is a separate OAuth client and gets its own connection. Claude Desktop on your laptop and Claude Desktop on your work machine appear as two entries in Mokaru → Settings → MCP connections. You can revoke them independently.
  </Accordion>

  <Accordion title="I get rate-limit errors">
    The MCP endpoint enforces two limits: 100 requests per 10 seconds per IP, and 60 requests per minute per OAuth client. Individual `/v1/*` endpoints also have their own rate limits. Wait the `Retry-After` seconds returned in the `RateLimit-Reset` header.
  </Accordion>

  <Accordion title="How do I disconnect?">
    Mokaru → **Settings → Integrations → MCP connections**. Click **Disconnect** on the agent you want to revoke. All access tokens for that agent stop working immediately.
  </Accordion>
</AccordionGroup>

## Don't see your client?

Any MCP-compatible client that supports the **streamable HTTP transport** and **OAuth 2.1** works against `https://api.mokaru.ai/mcp`. If your client only supports stdio transport, it cannot connect to a remote MCP server.

Found a client that should be listed here? Email us at [support@mokaru.ai](mailto:support@mokaru.ai) and we'll add setup steps.