# Connect AI assistants to Samskrift

> Samskrift speaks MCP, so Claude, ChatGPT and other AI tools can open your projects, edit files, compile, and join the project chat — signed in as you, with every change landing in version history like any other edit.

MCP link (Streamable HTTP, OAuth sign-in): `https://samskrift.com/mcp`

## How to connect

### Claude

1. **Open Claude's connector settings.** On claude.ai, go to Settings → Connectors.
2. **Click “Add custom connector”.**
3. **Name it Samskrift and paste the link.** `https://samskrift.com/mcp`
4. **Click Add and finish sign-in.** Claude opens a Samskrift sign-in — log in with your usual account and approve access.
5. **Use it in a chat.** Enable Samskrift from the tools menu in the composer, then try “List my Samskrift projects”.

### Claude Code

1. **Run the install command in your terminal.** `claude mcp add --scope user --transport http samskrift https://samskrift.com/mcp`
2. **Start Claude Code and run /mcp.** Samskrift should be listed. Select it and choose Authenticate to sign in with your Samskrift account.
3. **Prompt Claude Code to use Samskrift.** For example: “Open my thesis project on Samskrift, read main.tex, and fix the compile errors.”

### ChatGPT

1. **Open Plugins in ChatGPT.** Go to chatgpt.com/plugins (also in the sidebar), click the + button and choose “Add custom MCP server”. Don't see that option? Custom servers follow your plan and workspace policy — a workspace admin may need to allow them.
2. **Name it Samskrift and paste the link.** Keep OAuth as the sign-in method. `https://samskrift.com/mcp`
3. **Accept the notice and click “Create as a plugin”.** ChatGPT opens a Samskrift sign-in — log in with your usual account and approve access.
4. **Use it in a chat.** Install the plugin, then type @Samskrift in the prompt box or simply ask “List my Samskrift projects”.

### Codex

1. **Run the install command in your terminal.** `codex mcp add samskrift --url https://samskrift.com/mcp`
2. **Sign in.** Approve access in the browser window that opens. `codex mcp login samskrift`
3. **Prompt Codex to use Samskrift.** For example: “List my Samskrift projects, then read main.tex in the newest one.”

### Others

1. **Open your assistant's MCP or custom connector settings.** Most AI tools that support MCP call this “custom connectors”, “remote MCP servers”, or “integrations”.
2. **Create a remote MCP server connection.** Choose the remote / Streamable HTTP option if asked.
3. **Name the connection and paste the link.** `https://samskrift.com/mcp`
4. **Finish the sign-in prompt.** Samskrift protects its tools with OAuth, so you'll sign in with your own account and approve access.
5. **Ask the assistant to list your Samskrift projects.** That's the quickest way to confirm everything is connected.

## What connected agents can do

- **Projects:** List your projects, create new ones (blank or from a zip), rename them, switch LaTeX engines, set the main file, and manage labels.
- **Files:** Read any file, make precise edits, create, rename, and delete files, upload figures, and search across the whole project.
- **Build & history:** Compile and get parsed error reports, download the finished PDF, and browse version history — any file can be restored as of any edit.
- **Collaboration:** Post in project chat, add and resolve inline comments, create share links, and invite collaborators.

## Good to know

- An assistant signs in as you — it can only reach projects your account can, and you can disconnect it from your AI tool's settings at any time.
- Agent edits flow through the same collaborative engine as the web editor: collaborators see them live, and every change is in version history, so anything can be reverted.
- Chat messages an agent sends post under your name, so it's asked to sign them (e.g. “[agent]”) so co-authors know a machine wrote them.

## Tool reference

### list_projects (read-only)

List the LaTeX projects the signed-in user can access on Samskrift, with their id, name, your role (owner/editor/viewer), labels, compiler, and last-updated time. Use the returned id (or exact name) as the `project` argument for the other tools.

- `search` (string): Optional name filter (substring match).

### create_project

Create a new Samskrift LaTeX project, either from a zip archive (pass the zip as base64, or an https URL to fetch it from) or as a blank article skeleton when no zip is given. Zip imports recreate the full folder tree, store text files with version history, upload binary assets (images, PDFs, fonts), and auto-detect the main .tex file — just like the web app's Upload Project flow.

- `name` (string, required): Name for the new project.
- `zip_base64` (string): Base64-encoded .zip archive of the project (e.g. from `base64 project.zip`). Mutually exclusive with zip_url.
- `zip_url` (string): HTTPS URL of a .zip archive to import. Mutually exclusive with zip_base64.
- `compiler` ("pdflatex" | "xelatex" | "lualatex" | "latex"): LaTeX engine for the project (defaults to pdflatex).

### update_project

Change a Samskrift project's settings: rename it, switch the LaTeX engine (pdflatex/xelatex/lualatex/latex), or set which .tex file is the main document that compile_project builds. Pass only the fields you want to change.

- `project` (string, required): Project id (preferred) or exact project name.
- `name` (string): New project name.
- `compiler` ("pdflatex" | "xelatex" | "lualatex" | "latex"): LaTeX engine to compile with.
- `main_file` (string): Path of the text file to use as the main document, e.g. main.tex

### list_files (read-only)

List every file and folder in a Samskrift project as full paths, marking which are editable text files, which are binary assets (images etc.), and which is the main document.

- `project` (string, required): Project id (preferred) or exact project name.

### read_file (read-only)

Read the text content of a file in a Samskrift project (LaTeX sources, .bib, .cls, etc.), optionally a specific line range and with line numbers. Binary assets like images cannot be read as text.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Full path inside the project, e.g. chapters/intro.tex
- `line_start` (integer): First line to return (1-based). Omit to read from the top.
- `line_end` (integer): Last line to return (inclusive). Omit to read to the end.
- `line_numbers` (boolean): Prefix each line with its line number — useful before a targeted edit_file.

### write_file

Replace the entire text content of an existing file in a Samskrift project. For small targeted changes prefer edit_file, which patches by search-and-replace instead of resending the whole file. The edit is applied through the same collaborative engine as the web editor: it appears instantly for anyone with the file open, and is recorded in the project's version history.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Full path of an existing text file, e.g. main.tex
- `content` (string, required): The complete new file content.

### edit_file

Make targeted edits to a text file by exact search-and-replace — like a patch, without resending the whole file. Each edit's old_text must match the file exactly (including whitespace); all edits are validated first and then applied atomically in order. Changes go through the collaborative engine: they appear live for collaborators and are recorded in version history. Prefer this over write_file for small changes.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Full path of an existing text file, e.g. main.tex
- `edits` (array of objects, required): Edits applied in order. If any edit fails to match, nothing is written.

### create_file

Create a new text file (e.g. .tex, .bib, .sty) in a Samskrift project, creating intermediate folders as needed. Binary assets such as images must be uploaded through the web app instead.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Full path for the new file, e.g. chapters/methods.tex
- `content` (string): Initial file content (defaults to empty).

### rename_file

Rename or move a file or folder in a Samskrift project by giving its current path and the desired new full path. The file keeps its identity, so version history, comments, and live collaboration are all preserved — this is the right way to reorganize (never delete + recreate). Intermediate folders in the new path are created automatically.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Current full path, e.g. chapters/old-name.tex
- `new_path` (string, required): New full path, e.g. chapters/methods.tex or figures/plots/plot1.png

### delete_file

Delete a file (or an empty folder) from a Samskrift project. This is permanent — the file's content is removed for all collaborators.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Full path of the file to delete.

### upload_asset

Upload a file into a Samskrift project from base64 bytes — the MCP counterpart of dragging a file into the web editor. Binary files (images, PDFs, fonts) are stored as assets usable from \includegraphics etc.; text files are stored as editable documents with version history. An upload to an existing path replaces that file (set overwrite to false to forbid this). Max 15 MB.

- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string, required): Full destination path, e.g. figures/plot1.png — folders are created as needed.
- `base64` (string, required): The file bytes as base64 (e.g. from `base64 plot1.png`). data: URLs are accepted.
- `overwrite` (boolean): Replace an existing file at that path (default true, like the web app).

### search_project (read-only)

Search all text files in a Samskrift project for a string or regular expression. Returns matching lines with file paths and line numbers, like grep.

- `project` (string, required): Project id (preferred) or exact project name.
- `query` (string, required): Text or regular expression to search for.
- `regex` (boolean): Treat the query as a regular expression.
- `case_sensitive` (boolean): Match case exactly.

### project_history

Browse and restore the per-edit version history of a Samskrift project. Every keystroke batch by every author (human, web, or MCP) is logged. Actions: 'list' shows recent edits (project-wide, or for one file when path is given) with edit ids; 'read' reconstructs a file's exact content as it was right after a given edit_id; 'restore' writes that reconstructed content back as a NEW edit (non-destructive — the restore itself is logged, so you can always come back).

- `action` ("list" | "read" | "restore", required): 'list' recent edits, 'read' a file at a point in time, or 'restore' it.
- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string): File path — required for read/restore, optional filter for list.
- `edit_id` (integer): Edit id from 'list' — required for read/restore.
- `limit` (integer): How many edits to list (default 30).

### compile_project

Compile a Samskrift project to PDF with its configured LaTeX engine. Returns a pass/fail summary with parsed errors and warnings (file, line, message). On success the PDF is cached so the web app shows the fresh build.

- `project` (string, required): Project id (preferred) or exact project name.
- `draft` (boolean): Compile with LaTeX draft mode: much faster, but images render as placeholder boxes. The result is not cached as the project's PDF.

### get_pdf (read-only)

Get a temporary download link (valid 1 hour) for a Samskrift project's most recently compiled PDF — the cached result of the last compile_project call or web-app build. Useful for fetching and reviewing the finished document. If no PDF is cached yet, run compile_project first.

- `project` (string, required): Project id (preferred) or exact project name.

### read_chat (read-only)

Read the recent messages in a Samskrift project's built-in chat (the same chat collaborators use in the web editor). Use this to catch up on what human collaborators are discussing or asking for before making changes, and send_chat_message to answer them.

- `project` (string, required): Project id (preferred) or exact project name.
- `limit` (integer): How many of the latest messages to return (default 50).

### send_chat_message

Post a message to a Samskrift project's built-in chat, visible instantly to all collaborators in the web editor. The message appears under the signed-in user's name, so make clear when you (the agent) are speaking — e.g. prefix with “[agent]” or sign off. Great for announcing what you changed or asking humans a question; pair with read_chat to hold a conversation.

- `project` (string, required): Project id (preferred) or exact project name.
- `message` (string, required): The message to post.

### comments

Work with a Samskrift project's inline review comments — the threads collaborators see highlighted in the web editor's Review panel. Actions: 'list' shows threads (file, line range, quoted text, full conversation), 'add' starts a new thread anchored to an exact snippet of a file's text (the anchor follows the text as it is edited), 'reply' adds a message to a thread, 'resolve'/'reopen' close or revive it. This is the best channel for line-level questions and review feedback between humans and agents.

- `action` ("list" | "add" | "reply" | "resolve" | "reopen", required): What to do with comment threads.
- `project` (string, required): Project id (preferred) or exact project name.
- `path` (string): File path — required for 'add', optional filter for 'list'.
- `quoted` (string): For 'add': the exact snippet of the file's current text to anchor the comment to. Must match exactly once — include more context if it's ambiguous.
- `message` (string): The comment text — required for 'add' and 'reply'.
- `thread` (string): Thread id (or unique id prefix, min 6 chars) — required for reply/resolve/reopen.
- `include_resolved` (boolean): For 'list': also include resolved threads.

### label_project

Add or remove a label (tag) on a Samskrift project for organizing the dashboard. Labels are personal to the signed-in user; adding a label that doesn't exist yet creates it. Use action 'list' to see all your labels.

- `action` ("add" | "remove" | "list", required): Add/remove a label on a project, or list all your labels.
- `project` (string): Project id or exact name (required for add/remove).
- `label` (string): Label name (required for add/remove).
- `color` (string): Hex color for a newly created label, e.g. #1971C2.

### share_project

Get, enable, or disable the share links of a Samskrift project you own. When sharing is on there are two secret links: an edit link (anyone with it can join as an editor after signing in) and a view link (read-only, no account needed). No emails are sent — send the link yourself.

- `project` (string, required): Project id (preferred) or exact project name.
- `action` ("get" | "enable" | "disable"): 'get' returns the current links, 'enable'/'disable' switch link sharing.

### invite_collaborator

Add a collaborator to a Samskrift project you own, by email, as an editor or viewer. If they already have an account they get access immediately; otherwise access is granted automatically when they sign up with that email. Either way Samskrift emails them a branded invitation naming the inviter, the project, and their access level, with a link to open it.

- `project` (string, required): Project id (preferred) or exact project name.
- `email` (string, required): The collaborator's email address.
- `role` ("editor" | "viewer"): Their access level.

---

HTML version: https://samskrift.com/connect · Site overview for language models: https://samskrift.com/llms.txt