🤖 MCP server

Warning

The MCP server is experimental.

It depends on your OIDC provider acting as a CIMD-capable authorisation server, and the surrounding ecosystem is still stabilising.

There are also 2 known issues ocurred during the development in combination with Keycloak:

• Keycloak missing “none” in token_endpoint_auth_methods_supported breaks MCP CIMD

• Keycloak CIMD tokens omit aud, so MCP access tokens aren’t audience-bound to TINO

It is disabled by default — enable it at your own risk.

See also

Have a look at the 🔭 Vision for where AI-driven document generation fits into TINO’s direction, and ADR-10: MCP server for the design rationale.

TINO ships with a built-in Model Context Protocol (MCP) server that exposes buckets, files, compilation, and git as tools for AI agents. An assistant can list buckets, read and write Typst files, compile them to check for errors, and commit the result. All through TINO, with the same access rules as a human user.

Connecting a client

1. Enable the MCP server (see TINO_MCP_ENABLED)

2. Point any MCP-capable client at https://<your-tino-host>/mcp (server is mounted at /mcp).

With the Claude Code CLI:

$ claude mcp add --transport http tino https://tino.example.com/mcp

Hint

The CLI opens your browser for the OAuth login, then connects. No token needs to be copied or configured by hand — the client identifies itself with a CIMD and obtains the token automatically.

Authentication

MCP clients authenticate via OAuth 2.0, as documented in the authentication chapter.

Available tools

Each tool enforces the minimum role the user must hold on the target bucket:

Tool	Min. role	Description
list_buckets	—	List buckets the user can access, with their role and per-bucket instructions.
list_files	Viewer	List files and directories in a bucket.
read_file	Viewer	Read a file’s text content.
compile_typst	Viewer	Compile a file and report success or the compiler error.
git_status	Viewer	Show the working-tree status of a bucket.
git_log	Viewer	Show commit history, optionally for a single file.
write_file	Editor	Create or overwrite a text file.
delete_file	Editor	Delete a file.
rename_file	Editor	Rename or move a file.
create_dir	Editor	Create an empty directory.
rename_dir	Editor	Rename or move a directory and its contents.
delete_dir	Editor	Delete a directory and all its contents.
commit	Committer	Commit changes to the bucket’s git repository.

Hint

The compile_typst tool lets an agent verify its own work: after editing a file it can compile, read the error, fix the source, and only commit once the document is valid.

Instructions

MCP instructions let you control how AI agents interact with TINO. They are included in the server’s context so the agent sees them before it starts working.

Global instructions

Scope

Global instructions apply to every MCP session.

Configuration

Set the TINO_MCP_INSTRUCTIONS environment variable to provide organisation-wide guidance.

Example usage

Define the communication style, terminology, or policies, e.g.:

• Use “we” instead of “I” in all documents.

• Don’t assume anything; always ask the user first.

• Never commit without approval.

Note

The text is appended to TINO’s built-in instructions.

Per-bucket instructions

Scope

Per-bucket instructions apply to a single bucket.

Configuration

Edit them in the bucket settings dialog (Bucket MCP instructions) or via the REST API (mcp_instructions in the bucket metadata). They are stored in the bucket’s .meta.yml and returned by the list_buckets tool so the agent sees them when it discovers available buckets.

Example usage

Describe the bucket’s content, structure, and conventions, e.g.:

• Write all content in British English.

• Place new customer-related documents in a customers/{customer name}/ directory.

• Never modify files under templates/.