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

# ModernLoop MCP

> Connect your AI agent to the ModernLoop MCP Server.

The ModernLoop MCP Server exposes scheduling data and actions as tools your AI agent can call. Select your client below to connect.

<Note>
  ModernLoop does not yet offer official marketplace or directory integrations. Use the custom
  connector steps for every client.
</Note>

<Tabs sync={false}>
  <Tab title="ChatGPT">
    Connect ChatGPT to ModernLoop with a custom MCP connector.

    1. Open **ChatGPT** → **Settings** → **Connectors** (or **Apps & Connectors**).
    2. Choose **Add connector** or **Create custom connector**.
    3. Enter a name such as `ModernLoop`.
    4. Set the server URL to one of the endpoints below.
    5. Save the connector and complete the ModernLoop OAuth sign-in when prompted.

    <CodeGroup>
      ```text Read and write theme={"dark"}
      https://api.modernloop.io/mcp
      ```

      ```text Read-only theme={"dark"}
      https://api.modernloop.io/mcp/readonly
      ```
    </CodeGroup>

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Claude">
    Connect Claude on the web or desktop with a custom MCP connector.

    1. Open **Claude** → **Settings** → **Connectors** (or **Integrations**).
    2. Choose **Add custom connector** or **Add MCP server**.
    3. Enter a name such as `ModernLoop`.
    4. Set the server URL to one of the endpoints below.
    5. Save and complete the ModernLoop OAuth sign-in when prompted.

    <CodeGroup>
      ```text Read and write theme={"dark"}
      https://api.modernloop.io/mcp
      ```

      ```text Read-only theme={"dark"}
      https://api.modernloop.io/mcp/readonly
      ```
    </CodeGroup>

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Claude Code">
    Add the ModernLoop MCP server from a terminal, then complete OAuth sign-in in Claude Code.

    <CodeGroup>
      ```bash Read and write theme={"dark"}
      claude mcp add --transport http modernloop \
        https://api.modernloop.io/mcp
      ```

      ```bash Read-only theme={"dark"}
      claude mcp add --transport http modernloop-readonly \
        https://api.modernloop.io/mcp/readonly
      ```
    </CodeGroup>

    Use `--scope user` to make the connection available in every project, or `--scope project` to share its configuration with one project. Do not commit credentials.

    Alternatively, add the server to your Claude Code MCP configuration file:

    <CodeGroup>
      ```json Read and write ~/.claude.json theme={"dark"}
      {
        "mcpServers": {
          "modernloop": {
            "type": "http",
            "url": "https://api.modernloop.io/mcp"
          }
        }
      }
      ```

      ```json Read-only ~/.claude.json theme={"dark"}
      {
        "mcpServers": {
          "modernloop-readonly": {
            "type": "http",
            "url": "https://api.modernloop.io/mcp/readonly"
          }
        }
      }
      ```
    </CodeGroup>

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Codex">
    Add the ModernLoop MCP server, then start its OAuth sign-in flow.

    <CodeGroup>
      ```bash Read and write theme={"dark"}
      codex mcp add modernloop \
        --url https://api.modernloop.io/mcp
      codex mcp login modernloop
      ```

      ```bash Read-only theme={"dark"}
      codex mcp add modernloop-readonly \
        --url https://api.modernloop.io/mcp/readonly
      codex mcp login modernloop-readonly
      ```
    </CodeGroup>

    Alternatively, add the server to `~/.codex/config.toml`:

    <CodeGroup>
      ```toml Read and write theme={"dark"}
      [mcp_servers.modernloop]
      url = "https://api.modernloop.io/mcp"
      ```

      ```toml Read-only theme={"dark"}
      [mcp_servers.modernloop-readonly]
      url = "https://api.modernloop.io/mcp/readonly"
      ```
    </CodeGroup>

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Copilot CLI">
    Add the ModernLoop MCP server with the Copilot CLI, then complete OAuth sign-in.

    <CodeGroup>
      ```bash Read and write theme={"dark"}
      copilot mcp add modernloop \
        --url https://api.modernloop.io/mcp
      ```

      ```bash Read-only theme={"dark"}
      copilot mcp add modernloop-readonly \
        --url https://api.modernloop.io/mcp/readonly
      ```
    </CodeGroup>

    Alternatively, add the server to `~/.copilot/mcp-config.json`:

    <CodeGroup>
      ```json Read and write theme={"dark"}
      {
        "mcpServers": {
          "modernloop": {
            "type": "http",
            "url": "https://api.modernloop.io/mcp"
          }
        }
      }
      ```

      ```json Read-only theme={"dark"}
      {
        "mcpServers": {
          "modernloop-readonly": {
            "type": "http",
            "url": "https://api.modernloop.io/mcp/readonly"
          }
        }
      }
      ```
    </CodeGroup>

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Cursor">
    Add the ModernLoop MCP server in Cursor settings or your MCP configuration file.

    **In Cursor:**

    1. Open **Settings** → **Tools & MCP** → **New MCP Server**.
    2. Choose an HTTP server.
    3. Enter one of the endpoint URLs below.
    4. Save. Cursor starts the OAuth sign-in flow when it connects.

    **From the terminal:**

    <CodeGroup>
      ```bash Read and write theme={"dark"}
      cursor --add-mcp '{"name":"modernloop","url":"https://api.modernloop.io/mcp"}'
      ```

      ```bash Read-only theme={"dark"}
      cursor --add-mcp '{"name":"modernloop-readonly","url":"https://api.modernloop.io/mcp/readonly"}'
      ```
    </CodeGroup>

    **In `~/.cursor/mcp.json` or project `.cursor/mcp.json`:**

    <CodeGroup>
      ```json Read and write theme={"dark"}
      {
        "mcpServers": {
          "modernloop": {
            "url": "https://api.modernloop.io/mcp"
          }
        }
      }
      ```

      ```json Read-only theme={"dark"}
      {
        "mcpServers": {
          "modernloop-readonly": {
            "url": "https://api.modernloop.io/mcp/readonly"
          }
        }
      }
      ```
    </CodeGroup>

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Gemini CLI">
    Add the ModernLoop MCP server with the Gemini CLI.

    <CodeGroup>
      ```bash Read and write theme={"dark"}
      gemini mcp add modernloop \
        --url https://api.modernloop.io/mcp
      ```

      ```bash Read-only theme={"dark"}
      gemini mcp add modernloop-readonly \
        --url https://api.modernloop.io/mcp/readonly
      ```
    </CodeGroup>

    Alternatively, add the server to `~/.gemini/settings.json`:

    <CodeGroup>
      ```json Read and write theme={"dark"}
      {
        "mcpServers": {
          "modernloop": {
            "httpUrl": "https://api.modernloop.io/mcp"
          }
        }
      }
      ```

      ```json Read-only theme={"dark"}
      {
        "mcpServers": {
          "modernloop-readonly": {
            "httpUrl": "https://api.modernloop.io/mcp/readonly"
          }
        }
      }
      ```
    </CodeGroup>

    Complete the ModernLoop OAuth sign-in when the client prompts you.

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>

  <Tab title="Other">
    Configure a remote Streamable HTTP MCP server with one of the ModernLoop endpoint URLs.

    <CodeGroup>
      ```json Read and write theme={"dark"}
      {
        "mcpServers": {
          "modernloop": {
            "type": "http",
            "url": "https://api.modernloop.io/mcp"
          }
        }
      }
      ```

      ```json Read-only theme={"dark"}
      {
        "mcpServers": {
          "modernloop-readonly": {
            "type": "http",
            "url": "https://api.modernloop.io/mcp/readonly"
          }
        }
      }
      ```
    </CodeGroup>

    Your client must support OAuth authorization-code flow with PKCE and dynamic client registration. It should follow the `WWW-Authenticate` challenge and the protected-resource metadata published by the endpoint.

    Use the read-only endpoint unless your workflow needs to change ModernLoop data. See [Toolsets](/mcp/toolsets) for details.

    Verify that your connection can list tools and that the granted scopes match your workflow.
  </Tab>
</Tabs>

## Toolsets

ModernLoop provides two toolsets. Each maps to a separate endpoint and OAuth resource.

| Toolset   | Endpoint                                 |                Tools |
| --------- | ---------------------------------------- | -------------------: |
| Read-only | `https://api.modernloop.io/mcp/readonly` |      Read tools only |
| Default   | `https://api.modernloop.io/mcp`          | Read and write tools |

A token for one endpoint cannot call the other. See [MCP Toolsets](/mcp/toolsets) for the full comparison.

## Supported clients

| Client                 | Connection method                                 | Notes                               |
| ---------------------- | ------------------------------------------------- | ----------------------------------- |
| ChatGPT                | Custom connector                                  | OAuth during connector setup        |
| Claude                 | Custom connector                                  | OAuth during connector setup        |
| Claude Code            | `claude mcp add` or `~/.claude.json`              | OAuth during first use              |
| Codex                  | `codex mcp add` or `~/.codex/config.toml`         | `codex mcp login` for OAuth         |
| Copilot CLI            | `copilot mcp add` or `~/.copilot/mcp-config.json` | OAuth during first use              |
| Cursor                 | Settings, CLI, or `mcp.json`                      | OAuth during first use              |
| Gemini CLI             | `gemini mcp add` or `~/.gemini/settings.json`     | OAuth during first use              |
| Other HTTP MCP clients | Generic `mcpServers` config                       | Must support OAuth 2.1 + PKCE + DCR |

## Required permissions

Each MCP tool requires an OAuth scope. Grant only the scopes your workflow needs.

### Read scopes

| Scope                    | Grants access to                      |
| ------------------------ | ------------------------------------- |
| `applications:read`      | Application listing and lookup        |
| `candidates:read`        | Candidate listing and lookup          |
| `interview_modules:read` | Interview-module and membership reads |
| `interviews:read`        | Interview event listing and lookup    |
| `jobs:read`              | Job and job-stage listing and lookup  |
| `organization:read`      | Organization settings (read)          |
| `schedules:read`         | Schedule listing and lookup           |
| `tasks:read`             | Scheduling-task and task-queue reads  |
| `templates:read`         | Template listing and lookup           |
| `users:read`             | User listing and lookup               |

### Write scopes

| Scope                     | Grants access to                           |
| ------------------------- | ------------------------------------------ |
| `applications:write`      | Application updates                        |
| `candidates:write`        | Candidate updates                          |
| `interview_modules:write` | Interview-module and membership writes     |
| `jobs:write`              | Job and job-stage updates                  |
| `organization:write`      | Organization settings updates              |
| `scheduling:write`        | Scheduling-task create, update, and cancel |
| `users:write`             | User updates                               |

The read-only endpoint accepts read scopes only. The default endpoint accepts read and write scopes.

Tools for resources your organization cannot access return not found.

## Troubleshooting access

### A tool is missing from `tools/list`

`tools/list` is scoped to the current session. A missing write tool usually means the client is connected to `/mcp/readonly`; that endpoint never exposes write tools. A missing read or write tool can also mean the token was not granted its required scope, or the organization does not have the corresponding entitlement. Check the [tool reference](/mcp/tools) for the exact scope and endpoint requirement.

### A tool call returns `NOT_FOUND`

If the tool appears in `tools/list` but its call returns `NOT_FOUND`, the ID may be unknown, deleted, outside the authenticated organization, or inaccessible to that organization. Confirm the ID with its list tool and make sure you are using the same organization. Do not infer that a missing tool is callable by guessing its name: reconnect with the required scope or endpoint and check `tools/list` again.

### I need additional scopes

Reconnect the MCP server and start a fresh OAuth authorization flow requesting the additional scopes. Depending on your client, remove and re-add the connector or sign out/revoke the existing ModernLoop connection before reconnecting. Then complete consent again and call `get_me` and `tools/list` to verify the granted scopes and available tools. For a static API token, mint or obtain a replacement token with the required scopes.

### My token works on one endpoint but not the other

`/mcp` and `/mcp/readonly` are separate OAuth protected resources with distinct audiences. Their tokens are not interchangeable: use an access token issued for the exact endpoint URL your client calls. Re-authorize against the other endpoint rather than reusing the existing token.

## Authentication

### OAuth 2.1 (recommended)

OAuth is the recommended authentication method for interactive AI clients.

1. Your client connects to the MCP endpoint URL.
2. The server responds with a `WWW-Authenticate` challenge.
3. Your client fetches protected-resource metadata and discovers the authorization server.
4. Your client registers dynamically (RFC 7591) and starts an authorization-code flow with PKCE.
5. You sign in to ModernLoop and grant the requested scopes.
6. Your client exchanges the authorization code for an access token.

The identity that authorizes the connection is used for all tool calls.

### Static API token

If your client does not support OAuth, send a ModernLoop API token in the `Authorization` header.

```json theme={"dark"}
{
  "mcpServers": {
    "modernloop-readonly": {
      "url": "https://api.modernloop.io/mcp/readonly",
      "headers": {
        "Authorization": "Bearer ${MODERNLOOP_API_TOKEN}"
      }
    }
  }
}
```

Store the token in your client's secret store or environment. Do not commit tokens to source control.

The token must include the scopes required by the tools you call. Match the endpoint to the token's granted scopes.

## Test access to the MCP Server

1. Connect your client using one of the configurations above.
2. Complete OAuth sign-in or configure a valid API token.
3. Call `tools/list` and confirm the expected tools appear.
4. Call a read tool such as `get_organization` to verify authorization.

For local development, run the Platform API at `http://localhost:8787` and use `/mcp` or `/mcp/readonly` on that host. See the [Platform API README](https://github.com/modernloop/mloop-backend/tree/main/backend/node) for token minting.

## Further reading

* [MCP Toolsets](/mcp/toolsets) — read-only vs default toolset
* [MCP Tools](/mcp/tools) — per-tool reference
* [MCP Data Model](/mcp/data-model) — relationships, IDs, discovery, and pagination
* [ModernLoop Platform API](/) — REST API overview