Skip to main content
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 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).

Connect a client

Add a remote MCP server to your client with these settings:
SettingValue
TransportStreamable HTTP
URLhttps://api.macroscope.com/mcp
Protocol versionsTested with 2025-03-26 through 2026-07-28
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 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. Connected clients are listed on the 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.

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.

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.

Errors

A tool call that fails returns a result with isError: true and one text content block containing a JSON error:
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. These are the same failures the REST API reports with the HTTP statuses under Errors. Some failures reject the HTTP request before any tool runs:

Limits

Tool calls share the REST API’s per-key and per-workspace rate limits and 55-second timeout; see 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. 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.