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

# MCP server

> Expose your Refmatter workspace to Claude, Cursor, or any MCP client with one URL and your API key.

The MCP endpoint is `https://api.refmatter.com/mcp` (Streamable HTTP). It holds no credentials of its own: every client sends its workspace API key as a bearer token, and the server forwards it to the API. Requests without a key get `401`.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http refmatter https://api.refmatter.com/mcp \
      --header "Authorization: Bearer $REFMATTER_API_KEY"
    ```
  </Tab>

  <Tab title="Claude Desktop / Cursor">
    ```json theme={null}
    {
      "mcpServers": {
        "refmatter": {
          "url": "https://api.refmatter.com/mcp",
          "headers": { "Authorization": "Bearer <your workspace API key>" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local (stdio)">
    ```bash theme={null}
    SOCIAL_API_KEY=<key> SOCIAL_API_BASE_URL=https://api.refmatter.com/v1 \
      npx social-scraper-mcp
    ```
  </Tab>
</Tabs>

## Tools

| Tool                 | What it does                                         |
| -------------------- | ---------------------------------------------------- |
| `resolve_reference`  | Submit a public URL; returns the ingestion to poll   |
| `get_ingestion`      | Read state, progress, and `referenceId`              |
| `list_references`    | Page through the workspace catalog with filters      |
| `get_reference`      | Full reference: observed, derived, human, provenance |
| `update_reference`   | Notes, tags, custom title (with revision)            |
| `delete_reference`   | Soft-delete and release the hold                     |
| `get_media_access`   | Short-lived download URL for video or poster         |
| `extend_media_hold`  | Keep the bytes for more days                         |
| `list_source_routes` | What the deployment can acquire right now            |

The `social://openapi` resource exposes the API contract so an agent can read the exact schemas.

## Example prompts

* "Save this YouTube video as a reference and tell me when the media is ready."
* "List my references tagged `hook` from the last week and summarize their titles."
* "Extend the media hold on the last reference to 90 days."