Connect a client
Add a remote MCP server to your client with these settings:| Setting | Value |
|---|---|
| Transport | Streamable HTTP |
| URL | https://api.macroscope.com/mcp |
| Protocol versions | Tested with 2025-03-26 through 2026-07-28 |
400. Requests a browser sends from another website’s origin are rejected with 403.
With an API key
Add the headerAuthorization: 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 noAuthorization 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 callget_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: asstructuredContent, 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’snextPageToken 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 withisError: 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 theRateLimit-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.