# MCP Docs

> MCP Docs is an editor for Word, PowerPoint and Excel files, PDFs, Markdown, CSV and pictures, with a built-in AI assistant and an MCP server so agents can work on the same files. It is a free, open-source desktop app for macOS and Windows (`npx @freeflow-im/mcp-docs` installs it and adds it to Claude Code and Codex), and a web app in beta.

The web app is at https://mcpdocs.freeflow.im. It is a single-page app whose pages need a browser; this file and the feature pages below are Markdown to read instead.

## Features

- [Edit PowerPoint presentations with your AI agent](https://mcpdocs.freeflow.im/features/presentations.md): Open, edit and save PowerPoint (.pptx) presentations with an AI assistant beside them, or let Claude Code, Codex or any MCP client build and edit the slides while you watch.
- [Excel spreadsheets your AI agent can work in](https://mcpdocs.freeflow.im/features/spreadsheets.md): Edit Excel (.xlsx) and CSV files with formulas, filters, charts and formatting, and let an AI assistant, Claude Code, Codex or any MCP client sort, clean up and fill in the data.
- [Word documents you write with your AI agent](https://mcpdocs.freeflow.im/features/documents.md): Write and edit Word (.docx) documents with headings, pictures and video, and let the built-in AI assistant, Claude Code, Codex or any MCP client draft and edit them with you.
- [A Markdown editor built for working with agents](https://mcpdocs.freeflow.im/features/markdown.md): A GitHub-flavored Markdown editor with a live preview and Mermaid diagrams, where the AI assistant, Claude Code, Codex or any MCP client edits the same files you do.
- [PDFs your AI agents can read](https://mcpdocs.freeflow.im/features/pdfs.md): Read and sign PDFs, and turn any PDF, scanned pages included, into Markdown that Claude Code, Codex and other AI agents can read and edit, with the free MCP Docs app.
- [An image editor you can ask](https://mcpdocs.freeflow.im/features/images.md): Crop, resize, adjust colors, add text and shapes and stack layers on your pictures, or ask the AI assistant to do it, background removal included, in the free MCP Docs app.
- [Office files for your AI agents, over MCP](https://mcpdocs.freeflow.im/features/ai-agents.md): Give Claude Code, Codex, Cursor or any MCP client the tools to open, read, create and edit Word, Excel and PowerPoint files, PDFs, Markdown and pictures, and watch each change in the MCP Docs app.

## MCP server

MCP Docs has a remote MCP server, so an agent can read and edit the files in a person's account.

- Endpoint: `https://mcpdocs.freeflow.im/mcp/v2` (streamable HTTP)
- Sign-in: OAuth 2.1. The person signs in to their own MCP Docs account and allows the agent; there are no API keys.
- Scopes: `files:read`, `files:write`
- Discovery: `https://mcpdocs.freeflow.im/.well-known/oauth-protected-resource/mcp/v2` and `https://mcpdocs.freeflow.im/.well-known/oauth-authorization-server`

### Connect with a browser on the same machine

Any MCP client that supports remote servers with OAuth can use the endpoint directly. In Claude Code:

```sh
claude mcp add --transport http universal-docs https://mcpdocs.freeflow.im/mcp/v2
```

The client opens a browser for the sign-in (authorization code flow with PKCE; dynamic client registration and client ID metadata documents are both supported).

### Connect without a browser (remote or headless agents)

The server supports the OAuth device authorization grant (RFC 8628). With [mcp-remote](https://github.com/punkpeye/mcp-remote):

```sh
npx -y mcp-remote https://mcpdocs.freeflow.im/mcp/v2 --device-code
```

Run that once in a terminal. It prints the address https://mcpdocs.freeflow.im/oauth/device and a short code. The person opens the address in any browser, on any machine, enters the code, signs in and allows the agent. The tokens are then saved, and later runs need no one. As a stdio server in an MCP client's configuration:

```json
{ "command": "npx", "args": ["-y", "mcp-remote", "https://mcpdocs.freeflow.im/mcp/v2", "--device-code"] }
```

Do the first sign-in in a terminal before starting the client: a client that launches the command itself usually hides the code and gives up before anyone can enter it. The person can see and disconnect these agents under Settings in the app.

### Connect by hand, over HTTP

An agent that makes the HTTP requests itself (with curl, say) signs in like this. All the token requests are forms (`application/x-www-form-urlencoded`).

1. Register once: POST `https://mcpdocs.freeflow.im/oauth/register` with JSON `{"client_name": "<your name>", "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"], "token_endpoint_auth_method": "none"}`. Keep the `client_id` it returns.
2. Ask for a code: POST `https://mcpdocs.freeflow.im/oauth/device_authorization` with `client_id` and `resource=https://mcpdocs.freeflow.im/mcp/v2`. It returns `device_code`, `user_code`, `verification_uri` and `interval`.
3. Show the person the `verification_uri` and the `user_code`, and poll: POST `https://mcpdocs.freeflow.im/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `device_code` and `client_id`, every `interval` seconds. `authorization_pending` means keep polling; `slow_down` means wait 5 seconds longer between polls from then on.
4. Once the person allows it, the response has an `access_token` (good for 7 days) and a `refresh_token` (good for 30 days). **Save both, and the `client_id`, somewhere that outlasts the session** (a file, not a variable): they are what lets you come back without asking the person again.
5. Call the MCP endpoint: POST `https://mcpdocs.freeflow.im/mcp/v2` with `Authorization: Bearer <access_token>`, `Content-Type: application/json`, `Accept: application/json, text/event-stream` and a JSON-RPC body (`tools/list`, `tools/call`).

**Do not ask the person for a new code when the access token expires. Refresh instead.** When a request is refused with 401 (its `reason` says `expired`), or before `expires_in` runs out:

```sh
curl -sS -X POST https://mcpdocs.freeflow.im/oauth/token -d grant_type=refresh_token -d refresh_token=<refresh_token> -d client_id=<client_id>
```

That returns a new `access_token` and a new `refresh_token`. Replace the saved ones with them: each refresh token works once, and sending an old one again signs the agent out. Every refresh gives another 30 days. Ask for a new code only if the refresh itself fails with `invalid_grant`. A 401 from the endpoint always says why, in `reason` and `error_description`.

### What the tools do

- Files: list, open, create, rename, delete and import (from a web address) documents, Markdown files, spreadsheets, presentations and stored files.
- Local files: `upload_file` returns a one-time address; POST the file's bytes to it (`curl --data-binary @file <address>`). Use it for files on the agent's own disk.
- Folders: `list_files` shows each file's folder and the folders there are; `create_folder` and `move_file` organize them, and `upload_file` can upload into one.
- Documents and Markdown: read as numbered blocks; insert, replace and delete blocks; replace text; format text and blocks; page setup.
- Spreadsheets: read and write ranges (formulas included), insert and delete rows and columns, sort, filter, format, freeze panes, tabs.
- Presentations: read a deck, add, update, move and delete slides, edit elements, set the theme.
- Stored files: read a file as it is, read its text, view and transform pictures.

Read before editing (`read_doc`, `read_deck`, `get_sheet_overview`): block and slide numbers change after inserts and deletes.

## Links

- [Support](https://mcpdocs.freeflow.im/support)
- [Privacy Policy](https://mcpdocs.freeflow.im/privacy)
- [Terms of Service](https://mcpdocs.freeflow.im/terms)