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

# MCP Server

> Connect your AI coding tools and Claude apps to Magna's docs with our hosted, public MCP server — search and read the documentation and API specs directly, no token required.

Magna hosts a **Model Context Protocol (MCP)** server at `https://docs.magna.so/mcp`. It lets AI coding tools (Claude Code, Cursor, VS Code, and other MCP-compatible clients) and Claude apps (Desktop, web, Cowork, mobile, and @Claude in Slack) search and read these docs directly — so your assistant answers Magna questions from the current documentation instead of guessing.

## Overview

* **Hosted and public.** The server runs on Magna's docs site. Search and filesystem access are **read-only and require no auth token** — just point your client at the URL.
* **Always current.** It serves the live documentation, including the Admin API and Portal API OpenAPI specs, so answers track the published docs rather than a model's training cut-off.
* **One non-read action.** The `submit_feedback` tool lets an assistant report a page that's wrong, outdated, or confusing straight to the Magna docs team — it doesn't modify anything on your side.

<Note>
  The server exposes documentation only. It does **not** touch your Magna
  account, projects, allocations, or the [Admin](/apis/admin/introduction) /
  [Portal](/apis/portal/overview) APIs — for those you still authenticate with
  your own API key. This server is purely a faster way to read the docs.
</Note>

### Exposed tools

The server exposes three tools plus a guidance resource. Tool names are generated per-site, so the exact strings your client shows may differ slightly — discover them from the server rather than hardcoding.

| Tool                                   | What it does                                                                                                                                                               |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`search_magna_docs`**                | Semantic search across the docs. Best for "where does Magna explain X?"                                                                                                    |
| **`query_docs_filesystem_magna_docs`** | Shell-style read access (grep / cat / tree / jq) over the doc files **and the OpenAPI specs**. Best for pulling exact wording, a full page, or a specific endpoint schema. |
| **`submit_feedback`**                  | Reports a documentation issue (page path + description) back to the Magna docs team. The one non-read action.                                                              |

It also serves an MCP **resource** — a short skill with guidance on token distributions, vesting, and the Admin and Portal APIs — that primes an assistant on Magna's domain before it searches.

<Tip>
  Use **search** to find the right page from a fuzzy question, and the
  **filesystem** tool when you already know what you want and need exact text —
  for example `cat`-ing an endpoint's schema out of the OpenAPI spec.
</Tip>

## Set up in your editor or CLI

Add the server once per tool. None of these need a token — leave any auth field empty.

<Tabs>
  <Tab title="Claude Code">
    Run:

    ```sh theme={null}
    claude mcp add --transport http magna-docs https://docs.magna.so/mcp
    ```

    Add `--scope user` to make it available across all your projects instead of only the current one:

    ```sh theme={null}
    claude mcp add --transport http --scope user magna-docs https://docs.magna.so/mcp
    ```

    Confirm it connected with `claude mcp list` (or `/mcp` inside a session) — the server should show `✔ Connected`.
  </Tab>

  <Tab title="Cursor">
    Add the server to your Cursor MCP config — `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` in a project root:

    ```json theme={null}
    {
      "mcpServers": {
        "magna-docs": {
          "url": "https://docs.magna.so/mcp"
        }
      }
    }
    ```

    Reload Cursor, then check **Settings → MCP** — `magna-docs` should list its tools with a green indicator. No token field is needed.
  </Tab>

  <Tab title="VS Code">
    Add the server to `.vscode/mcp.json` in your workspace (VS Code uses the `servers` key and an explicit `type`):

    ```json theme={null}
    {
      "servers": {
        "magna-docs": {
          "type": "http",
          "url": "https://docs.magna.so/mcp"
        }
      }
    }
    ```

    Save the file and start the server from the **Start** action VS Code shows above the entry. Its tools then appear in Chat's tool picker (agent mode).
  </Tab>

  <Tab title="Codex / other MCP clients">
    Most MCP-compatible clients accept a streamable-HTTP server entry. Use the client's config location (many use an `mcpServers` map):

    ```json theme={null}
    {
      "mcpServers": {
        "magna-docs": {
          "type": "streamable-http",
          "url": "https://docs.magna.so/mcp"
        }
      }
    }
    ```

    If a client only supports **stdio** servers, bridge to the remote URL with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

    ```json theme={null}
    {
      "mcpServers": {
        "magna-docs": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://docs.magna.so/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Set up in Claude apps

Custom connectors (remote MCP) are available on the **Free, Pro, Max, Team, and Enterprise** plans across claude.ai, Claude Desktop, Cowork, and the mobile apps. Free is limited to one custom connector. Because the Magna docs server is public, you don't add a token.

<Steps>
  <Step title="Open connector settings">
    Go to **Settings → Connectors** (shown as **Customize → Connectors** on some
    clients).
  </Step>

  <Step title="Add a custom connector">
    Click **+**, then **Add custom connector**.
  </Step>

  <Step title="Paste the URL">
    Enter a name (for example, `Magna Docs`) and the URL
    `https://docs.magna.so/mcp`. Leave the OAuth fields under **Advanced
    settings** empty — the server is public.
  </Step>

  <Step title="Add and use">
    Click **Add**. The connector's tools now appear in Claude's tool list; ask a
    Magna question and Claude will search the docs.
  </Step>
</Steps>

<Note>
  **Team and Enterprise plans:** an **Owner** must add the connector
  organization-wide first, under **Organization settings → Connectors → Add →
  Custom → Web**. After that, each member enables it individually from
  **Settings → Connectors → Connect**.
</Note>

## Use it with Claude in Slack

Connectors are tied to your **Claude account**, not to a Slack workspace — so a custom connector you add in Claude also works in @Claude in Slack, since Slack runs on the same linked account. There is **no separate MCP setup on the Slack side**.

<Steps>
  <Step title="Add the connector in Claude first">
    Follow [Set up in Claude apps](#set-up-in-claude-apps) to add
    `https://docs.magna.so/mcp` in your Claude account settings. You **cannot**
    add or manage connectors from inside Slack.
  </Step>

  <Step title="Use it in Slack">
    Mention **@Claude** in a channel or DM and ask a Magna question. It uses the
    same account-level tools you enabled in Claude, including this docs server.
  </Step>
</Steps>

<Note>
  Claude in Slack mirrors the tools enabled on your Claude account, but a few
  Claude features aren't available there (for example, Research and extended
  thinking), and you can't create new connections from Slack. Verified against
  Anthropic's
  [Use Claude in Slack](https://support.claude.com/en/articles/12461605-use-claude-in-slack)
  and
  [custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
  help articles.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The connector or its tools don't show up">
    * Confirm the URL is exactly `https://docs.magna.so/mcp` (with the `/mcp` path).
    * In Claude Code, run `claude mcp list` and look for `✔ Connected`; a `✘` means the client couldn't reach the server.
    * In Claude apps, reopen **Settings → Connectors** and toggle the connector off and on, then start a new chat so the tool list refreshes.
    * On Team/Enterprise, an Owner must add the connector org-wide before members can enable it — see the note above.
  </Accordion>

  <Accordion title="It asks for a token or OAuth credentials">
    This server is public and read-only, so no token is required. Leave any auth
    or OAuth fields empty. If a client forces a value, that's a client-side
    field — you can save it blank.
  </Accordion>

  <Accordion title="Search vs. filesystem — which tool?">
    Use **`search_magna_docs`** when you have a fuzzy question and need Claude to
    find the right page. Use **`query_docs_filesystem_magna_docs`** when you know
    what you want and need exact text — reading a full page, grepping for a term,
    or pulling a specific endpoint schema straight from the OpenAPI spec.
  </Accordion>

  <Accordion title="A doc page looks wrong or out of date">
    Ask your assistant to use the **`submit_feedback`** tool with the page path
    and a short description. It routes straight to the Magna docs team.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Admin API" icon="key" href="/apis/admin/introduction">
    The private, server-to-server API. The filesystem tool can read its OpenAPI
    spec directly from the docs.
  </Card>

  <Card title="Portal API" icon="globe" href="/apis/portal/overview">
    The public API behind claim portals. Its spec is also readable through this
    MCP server.
  </Card>
</CardGroup>