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

# MCP server

> Read workspace data from MCP clients and coding agents with an API key or your Macroscope sign-in.

Macroscope's hosted MCP server exposes the API's read-only operations as tools, so an MCP client or coding agent can read workspace reports, statistics, comments, commits and billing. Each tool performs exactly one API operation. None of them run agents, change settings, or incur usage charges.

A client connects with a workspace API key, as the [REST API](https://docs.macroscope.com/api) does, or by signing in to Macroscope in your browser. Tools return the same data as the REST API, but what a client can read depends on how it connects: a key has the permissions it was created with, and a sign-in has yours (see [Permissions](#permissions)).

## Connect a client

Add a remote MCP server to your client with these settings:

<table>
  <colgroup>
    <col width="151" />

    <col width="514" />
  </colgroup>

  <thead>
    <tr>
      <th>Setting</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Transport</td>
      <td>Streamable HTTP</td>
    </tr>

    <tr>
      <td>URL</td>
      <td>`https://api.macroscope.com/mcp`</td>
    </tr>

    <tr>
      <td>Protocol versions</td>
      <td>Tested with 2025-03-26 through 2026-07-28</td>
    </tr>
  </tbody>
</table>

The server answers each request with a single JSON response. It does not keep sessions, stream events or send notifications, and its tool list does not change while a client is connected. Send one JSON-RPC message per request: batches are rejected with `400`. Requests a browser sends from another website's origin are rejected with `403`.

### With an API key

Add the header `Authorization: Bearer $MACROSCOPE_API_KEY` to the server entry, and the client sends the key on every request. [Create an API key](https://docs.macroscope.com/api#create-an-api-key) if you do not have a key yet.

### By signing in

A client that implements MCP authorization can connect without a key. Add the server with no `Authorization` header. When the client first connects, it opens Macroscope in your browser. Choose the workspace the client may read and select **Allow access**, then return to the client.

| | API key | Sign-in |
| - | - | - |
| Acts as | The key, with the permissions it was created with | You, with your current access to the workspace |
| Workspace | The key's workspace | The workspace you chose when you allowed access |
| Works with | REST API and MCP server | MCP server only |
| Ends when | The key expires or is revoked | You disconnect the client, you lose read access to the workspace, or 90 days after you connected the client |

Connected clients are listed on the [Connected Apps](https://app.macroscope.com/settings/connected-apps) page of your account settings, with the workspace each one reads and when it was last used. Revoke a client there to end its access. The page is available even if you no longer belong to any workspace.

## Workspace

A key, or a sign-in, is bound to one workspace, and every tool reads that workspace. To read another workspace, add a second server entry. You can call `get_workspace` to confirm which workspace the client reads.

## Tools

Each tool's arguments and result fields match the endpoint's query parameters and response, with the same names, types, defaults and bounds. The workspace path parameters are the only difference: the key or sign-in supplies them.

| Tool | Endpoint |
| - | - |
| `get_workspace` | [Get workspace](https://docs.macroscope.com/api-reference/endpoint/get-workspace.md) |
| `list_areas` | [List areas](https://docs.macroscope.com/api-reference/endpoint/list-areas.md) |
| `get_workspace_report` | [Get workspace report](https://docs.macroscope.com/api-reference/endpoint/get-workspace-report.md) |
| `get_sprint_elapsed_hours` | [Get sprint elapsed hours](https://docs.macroscope.com/api-reference/endpoint/get-sprint-elapsed-hours.md) |
| `list_contributor_statistics` | [List contributor statistics](https://docs.macroscope.com/api-reference/endpoint/list-contributor-statistics.md) |
| `list_team_memberships` | [List team memberships](https://docs.macroscope.com/api-reference/endpoint/list-team-memberships.md) |
| `list_team_statistics` | [List team statistics](https://docs.macroscope.com/api-reference/endpoint/list-team-statistics.md) |
| `get_coding_time_statistics` | [Get coding time statistics](https://docs.macroscope.com/api-reference/endpoint/get-coding-time-statistics.md) |
| `query_code_review_statistics` | [Query code review statistics](https://docs.macroscope.com/api-reference/endpoint/query-code-review-statistics.md) |
| `list_code_review_comments` | [List code review comments](https://docs.macroscope.com/api-reference/endpoint/list-code-review-comments.md) |
| `query_approvability_statistics` | [Query approvability statistics](https://docs.macroscope.com/api-reference/endpoint/query-approvability-statistics.md) |
| `list_approvability_runs` | [List approvability runs](https://docs.macroscope.com/api-reference/endpoint/list-approvability-runs.md) |
| `list_commits` | [List commits](https://docs.macroscope.com/api-reference/endpoint/list-commits.md) |
| `get_billing_status` | [Get billing status](https://docs.macroscope.com/api-reference/endpoint/get-billing-status.md) |
| `get_billing_balance` | [Get billing balance](https://docs.macroscope.com/api-reference/endpoint/get-billing-balance.md) |
| `get_billing_controls` | [Get billing controls](https://docs.macroscope.com/api-reference/endpoint/get-billing-controls.md) |
| `list_billing_meter_summaries` | [List billing meter summaries](https://docs.macroscope.com/api-reference/endpoint/list-billing-meter-summaries.md) |
| `list_daily_billing_usage` | [List daily billing usage](https://docs.macroscope.com/api-reference/endpoint/list-daily-billing-usage.md) |
| `list_agent_credit_usage` | [List agent credit usage](https://docs.macroscope.com/api-reference/endpoint/list-agent-credit-usage.md) |
| `list_reporting_periods` | [List workspace reporting periods](https://docs.macroscope.com/api-reference/endpoint/list-workspace-reporting-periods.md) |
| `list_check_run_agent_billing_summaries` | [List check-run agent billing summaries](https://docs.macroscope.com/api-reference/endpoint/list-check-run-agent-billing-summaries.md) |

## Results

A successful call returns the endpoint's JSON response twice: as `structuredContent`, which matches the tool's output schema, and as the same JSON serialized in a single text content block for clients that read only text. The two are equivalent.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "workspace": {
        "name": "workspaces/GITHUB_ORGANIZATION/12345678",
        "workspaceType": "GITHUB_ORGANIZATION",
        "workspaceId": "12345678",
        "displayName": "acme",
        "timezone": "America/Los_Angeles",
        "createdAt": "2024-01-02T03:04:05Z",
        "reportingSchedule": {
          "cadence": "REPORTING_CADENCE_WEEKLY",
          "boundaryWeekday": 5,
          "boundaryHour": 18
        }
      }
    },
    "content": [
      {
        "type": "text",
        "text": "{\"workspace\":{\"name\":\"workspaces/GITHUB_ORGANIZATION/12345678\",\"workspaceType\":\"GITHUB_ORGANIZATION\",\"workspaceId\":\"12345678\",\"displayName\":\"acme\",\"timezone\":\"America/Los_Angeles\",\"createdAt\":\"2024-01-02T03:04:05Z\",\"reportingSchedule\":{\"cadence\":\"REPORTING_CADENCE_WEEKLY\",\"boundaryWeekday\":5,\"boundaryHour\":18}}}"
      }
    ]
  }
}
```

## Pagination

Paginated tools return one page per call. Pass the result's `nextPageToken` as the `pageToken` argument of the next call, with the same other arguments, until `nextPageToken` is absent. A short or empty page can still carry a token. Tokens are opaque: do not parse or construct them. Page size, token lifetime and consistency are the same as the REST API's; see [Pagination](https://docs.macroscope.com/api#pagination).

## Errors

A tool call that fails returns a result with `isError: true` and one text content block containing a JSON error:

```json theme={null}
{
  "error": {
    "code": "RESOURCE_EXHAUSTED",
    "message": "rate limited",
    "requestId": "6f1c2b9e-3d4a-4f5b-8c7d-2e1f0a9b8c7d",
    "retryAfterSeconds": 12
  }
}
```

`code` is a status code; the common ones are listed below. `message` describes the failure without data from outside the client's workspace. `requestId` identifies the request; include it in support requests. `retryAfterSeconds` is present only when the call was rate limited.

| `code` | Meaning |
| - | - |
| `INVALID_ARGUMENT` | An argument does not match the tool's input schema, or a value, date range or page token is invalid. The message names the rejected argument. |
| `PERMISSION_DENIED` | The key, or the signed-in person, lacks a permission the tool requires. |
| `NOT_FOUND` | The data does not exist for the workspace, for example Approvability is not available. |
| `RESOURCE_EXHAUSTED` | Rate limited (wait `retryAfterSeconds` before retrying), or the result is larger than 1 MiB (narrow the request with a smaller `pageSize`, a shorter date range or narrower filters; do not retry unchanged). |
| `DEADLINE_EXCEEDED` | The call ran past the 55-second timeout. Narrow the request before retrying. If the connection closes first, the client may receive no result at all. |
| `UNAVAILABLE` | The API is temporarily unavailable. Retry with backoff. |
| `INTERNAL` | Server error. Retry with backoff. |

These are the same failures the REST API reports with the HTTP statuses under [Errors](https://docs.macroscope.com/api#errors).

Some failures reject the HTTP request before any tool runs:

| HTTP | Meaning |
| - | - |
| `400` | A JSON-RPC batch, two different `Authorization` values, or a malformed body. |
| `401` | Missing, invalid, expired or revoked key or sign-in. Reconnect with a valid key, or sign in again. |
| `403` | The key or person cannot use the API, or the request came from a browser on another origin. |
| `413` | The request body is too large. |
| `429` | The limit for requests that do not reach the API was reached. Wait `Retry-After` seconds. |
| `503` | API temporarily unavailable. |

## Limits

Tool calls share the REST API's per-key and per-workspace rate limits and 55-second timeout; see [Limits](https://docs.macroscope.com/api#limits). A tool call that reaches the API counts against those limits. Every other request counts against a separate limit for each key, or each signed-in person, instead: connecting, listing tools, and tool calls rejected before they reach the API, such as an unknown tool name, arguments that do not match the input schema, a batch or an oversized body. In rare failures a request can count against both.

A signed-in person's tool calls count against a per-person limit in the workspace, the same size as a key's, shared by every client the person allows there, and against the workspace's limit, which they share with its API keys. Responses carry the `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers of the limit that applied.

## Permissions

Tools require the same permissions as their endpoints, described under [Permissions and scope](https://docs.macroscope.com/api#permissions-and-scope). A key has the permissions it was created with. A signed-in client has your current permissions in the workspace, which can differ from a key's: `get_billing_status` needs only read access, but the other billing tools need you to be a workspace admin, and the contributor, team and coding-time statistics tools need the Productivity permission. Fields an endpoint omits without a permission are omitted from the tool result too.

Sign-in grants read-only access to all supported data your permissions allow. You can't choose a narrower set of tools or data categories.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.