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

# MCP Server

> Give AI tools read-only access to your EquateIt data using natural language.

## What is an MCP Server?

MCP is an open protocol that standardizes how applications provide context to
LLMs. Among other benefits, it gives LLMs tools to act on your behalf.

The EquateIt MCP server lets MCP-aware tools — Claude Code, Claude Desktop,
Cursor, Windsurf and others — read your organisation's tutoring data through the
[EquateIt public API](/introduction). It is **read-only** and scoped to your
org, exactly like the REST API.

<Tip>
  Prefer not to install or run anything? Use the **hosted** server at
  `https://mcp.classquill.com/mcp` instead — see
  [AI Connectors](/connectors) to connect Claude (via OAuth), Codex, Composio
  and others. This page covers running the `equateit-mcp` package yourself.
</Tip>

Also listed on the [Smithery registry](https://smithery.ai/servers/collisbrandon02/classquill):

[![smithery badge](https://smithery.ai/badge/collisbrandon02/classquill)](https://smithery.ai/servers/collisbrandon02/classquill)

## What it can do

One tool per public endpoint, all read-only:

* **Sessions** — list and fetch tutoring sessions
* **Tutors** — list tutors and pull per-tutor earnings
* **Payments & invoices** — list payments received and invoices issued
* **Students & parents** — list students, parents, and a parent's balance
* **Curriculum** — subjects, classrooms, student groups, lesson plans, homework, results
* **Operations** — mileage trips, expense claims, and an owner reports summary

As an example, you could ask *"How much did each tutor earn last week?"* or
*"List the invoices that are still outstanding."*

## Prerequisites

* [Node.js](https://nodejs.org) 18 or later
* An EquateIt API key — create one in **Settings → Developers** (org admins
  only). See [Authentication](/authentication).

## How to use the MCP Server

The server is published to npm and runs with `npx` — there is nothing to install
or host. Replace `ei_live_xxxxxxxxx` with your own key throughout.

It supports two transports: **stdio** (default, runs locally) and **HTTP**.

### Stdio (default)

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add equateit -e EQUATEIT_API_KEY=ei_live_xxxxxxxxx -- npx -y equateit-mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Open the command palette → "Cursor Settings" → "MCP" → "Add new global MCP server".

    ```json theme={null}
    {
      "mcpServers": {
        "equateit": {
          "command": "npx",
          "args": ["-y", "equateit-mcp"],
          "env": { "EQUATEIT_API_KEY": "ei_live_xxxxxxxxx" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Open Claude Desktop settings → "Developer" → "Edit Config".

    ```json theme={null}
    {
      "mcpServers": {
        "equateit": {
          "command": "npx",
          "args": ["-y", "equateit-mcp"],
          "env": { "EQUATEIT_API_KEY": "ei_live_xxxxxxxxx" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    ```json theme={null}
    {
      "mcpServers": {
        "equateit": {
          "command": "npx",
          "args": ["-y", "equateit-mcp"],
          "env": { "EQUATEIT_API_KEY": "ei_live_xxxxxxxxx" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### HTTP transport

Run the server over HTTP for remote or web-based integrations. In HTTP mode each
client authenticates by passing its API key as a Bearer token.

Start the server:

```bash theme={null}
npx -y equateit-mcp --http --port 3000
```

It listens on `http://127.0.0.1:3000` and exposes the MCP endpoint at `/mcp`
using Streamable HTTP.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add equateit --transport http http://127.0.0.1:3000/mcp --header "Authorization: Bearer ei_live_xxxxxxxxx"
    ```
  </Tab>

  <Tab title="Cursor">
    ```json theme={null}
    {
      "mcpServers": {
        "equateit": {
          "url": "http://127.0.0.1:3000/mcp",
          "headers": { "Authorization": "Bearer ei_live_xxxxxxxxx" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Options

| Flag            | Env var                 | Default    | Purpose                                                                            |
| --------------- | ----------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `--key`         | `EQUATEIT_API_KEY`      | —          | Your `ei_live_...` key (stdio mode; HTTP mode reads the Bearer token per request). |
| `--http`        | —                       | off        | Use HTTP transport instead of stdio.                                               |
| `--port` / `-p` | `MCP_PORT`              | `3000`     | HTTP port.                                                                         |
| —               | `EQUATEIT_API_BASE_URL` | production | Backend base URL. Override to target staging.                                      |

<Info>
  The MCP server is a thin client over the REST API — all access control,
  org-scoping and [rate limits](/rate-limits) are enforced by the API itself.
  A key used here has the same read-only access it does everywhere.
</Info>