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

# Connect via MCP

> Connect Claude, Codex, and other MCP clients to Filed with OAuth, no API key required

<Warning>
  The Filed MCP server is not live in production yet. The connection details
  below are accurate for the built server, but the URLs will not resolve until
  it ships. Check with Filed before sharing this page with an integrator who
  needs it working today.
</Warning>

Filed runs a remote [MCP](https://modelcontextprotocol.io) server that lets AI
assistants like Claude and Codex act directly on a Filed workspace: run
GraphQL queries and mutations, upload documents, and read the API docs, all
without you writing any integration code.

Unlike the [API key model](/guides/authentication) used for custom
integrations, connecting an MCP client to Filed is a one-time OAuth consent
flow in your browser. There is no key to copy or paste.

```mermaid theme={null}
flowchart LR
  A["MCP client<br/>(Claude, Codex, ...)"] -->|"OAuth: register, authorize, consent"| B["Filed web app<br/>(sign in + approve)"]
  B -->|"surface refresh token"| C["Filed MCP server<br/>mcp.apps.filed.com"]
  C -->|"GraphQL"| D["Filed router<br/>router.apps.filed.com"]
```

## Connect a client

<Steps>
  ## Point your client at the MCP endpoint

  ```
  https://mcp.apps.filed.com/mcp
  ```

  | Client                          | How to add it                                                          |
  | ------------------------------- | ---------------------------------------------------------------------- |
  | **Claude.ai**                   | Settings → Connectors → Add custom connector → paste the URL above     |
  | **Claude Code**                 | `claude mcp add --transport http filed https://mcp.apps.filed.com/mcp` |
  | **ChatGPT** (developer mode)    | Paste the URL above as a custom connector                              |
  | **Codex** and other MCP clients | Add a remote server with the URL above, streamable HTTP transport      |

  ## Approve the connection

  Your client performs Dynamic Client Registration and redirects you to sign in
  to the Filed web app (if you aren't already) and approve the connection for a
  specific workspace. There is no key to generate or copy: approving the
  consent screen is the entire setup.

  ## Confirm it works

  Ask your assistant to call the `docs` tool, or run a simple query like `me`
  through `run_batch_queries`, to confirm the connection is live and scoped to
  the workspace you approved.
</Steps>

<Note>
  Approving the connection creates an MCP-type entry in the workspace's
  Integrations page, the same place API keys live. Revoke access at any time by
  deleting it there: the next request from that client gets a `401`.
</Note>

## What the server exposes

The MCP server does not expose the whole GraphQL schema as individual MCP
tools. Instead it gives your assistant a small number of general-purpose
tools and expects it to read the docs and write GraphQL itself.

| Tool                   | What it does                                                                                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs`                 | Points the assistant at the Filed API docs (this site), including the LLM-readable `/llms.txt` variant. Clients are instructed to call this first.  |
| `run_batch_queries`    | Runs one or more read-only GraphQL queries. Queries run in parallel (chunked, five at a time) and results come back in the same order as the input. |
| `run_batch_mutations`  | Runs one or more GraphQL mutations, in order. If one fails, the rest still run; check each result individually.                                     |
| `get_file_upload_info` | Returns a short-lived upload token and the platform's upload URL, for attaching documents to a client.                                              |

Your assistant can discover the full schema with a standard GraphQL
introspection query through `run_batch_queries`, the same schema documented in
the [API reference](/apis/introduction).

## How agents should choose APIs

Agents should use the API docs as a routing map, not only as schema reference.
The best default flow is:

1. Call `docs`, then read the [API introduction](/apis/introduction).
2. Call `run_batch_queries` with a small [`me`](/apis/me) query to confirm
   workspace scope.
3. Use [`Clients`](/apis/clients) to find the client by ID, name, or external
   identifier.
4. Use [`Binder`](/apis/binder) for organized files, source documents, missing
   items, counts, search, and signed document URLs.
5. Use [`Document messages`](/apis/document-messages) for notes, flags,
   comments, replies, hides, unhides, and sign-off writes.
6. Use [`Task triggers`](/apis/task-triggers) to start data entry or tax prep,
   then [`Tasks`](/apis/tasks) to poll status and errors.
7. Use [`Leadsheets`](/apis/leadsheets) to read tax prep output, issue state,
   trace, and existing sign-offs.
8. Use [`Integration capabilities`](/apis/integration-capabilities) when the
   user asks what an integration can do or asks to run a provider-specific
   action.

For reads, prefer `run_batch_queries` and batch independent lookups together.
For writes, prefer `run_batch_mutations` and check every result because a
failed mutation does not stop the rest of the batch.

<Note>
  The binder is usually the central object for client document work. It gives
  agents the subdocument IDs they need for notes, comments, sign-offs, leadsheet
  drilldown, and document search.
</Note>

## Uploading documents

MCP tool calls carry a single JSON message, so file bytes don't travel through
a tool call directly. To upload a document, the assistant:

1. Calls `get_file_upload_info` to get a short-lived (10-minute) upload token
   and the platform's [tus](https://tus.io) upload URL.
2. Drives the resumable tus upload directly against that URL, exactly as
   described in [Uploading documents](/guides/uploading-documents).
3. Passes the resulting `uploadId` into a mutation such as `createClient` or
   `addClientDocuments` through `run_batch_mutations`.

## Access and revocation

A connection is scoped to **one workspace**, chosen when you approve it. To
connect a second workspace, add another connection and approve it separately.

To revoke access, delete the connection from the workspace's Integrations
page. The next token exchange (within about two minutes, due to caching)
starts failing, and the next MCP request from that client gets a `401`.

## Troubleshooting

**The client won't complete the connection**

* Confirm you're signed in to the Filed web app in the same browser that
  completes the OAuth redirect.
* Confirm your MCP client supports streamable HTTP (not only SSE).

**Tool calls return `401`**

* The connection was revoked, or the underlying session cache expired and the
  next exchange failed. Reconnect the client.

**A mutation in `run_batch_mutations` failed but others succeeded**

* This is expected: mutations run in order and a failure doesn't stop the
  batch. Check each item's result individually rather than assuming
  all-or-nothing.