Connect a read-only MCP client to Limn
Run Limn's read-only MCP server with Codex, Claude Code, and other MCP-compatible clients to read public GitHub threads and decision history.
Prerequisites
- Node.js 18+ with npm/npx available
- An MCP-compatible client such as Codex or Claude Code
- A Limn account — sign in with GitHub here if you don't have one
- At least one public GitHub Markdown file with threads (or create your first below)
Create an API key
Go to Settings → API, create a named key, and copy it when shown.
The key is shown once and is separate from your browser session. Keep it out of version control and revoke it from Settings when it is no longer needed.
Add the MCP server to your client
No global installation is required. Add this entry to .claude/mcp.json:
{
"mcpServers": {
"limn": {
"command": "npx",
"args": ["-y", "@limn-sh/mcp"],
"env": {
"LIMN_API_URL": "https://api.limn.sh",
"LIMN_TOKEN": "limn_sk_REPLACE_WITH_KEY_FROM_SETTINGS"
}
}
}
}Replace the limn_sk_… placeholder with the revocable key from step 1. Browser session tokens are not accepted. Set LIMN_WORKSPACE_ROOT to your project root if you want line-accurate local anchoring.
For Codex, put the same key in the LIMN_TOKEN field of your trusted project's .codex/config.toml (or use the JSON config with a client that supports it):
[mcp_servers.limn]
command = "npx"
args = ["-y", "@limn-sh/mcp"]
[mcp_servers.limn.env]
LIMN_API_URL = "https://api.limn.sh"
LIMN_TOKEN = "limn_sk_REPLACE_WITH_KEY_FROM_SETTINGS"Open a Markdown file and verify
Restart your client, open any Markdown file in your project, then ask:
What open threads are there on the current file?Your agent will list all open threads on that file. If there are no threads yet, it will say so — that's correct behaviour.
Create your first thread (optional)
Paste any public GitHub Markdown URL into the Limn viewer, select a sentence, and add a comment. Then ask your agent about that file again — it will see the thread.
What your agent can do with Limn threads
- Read threads — the agent sees open discussions as structured context.
- Read decision history — the agent can retrieve resolved discussions.
- Discover files — the agent can list public GitHub files with open threads.
- Stay read-only — create, reply, and resolve actions remain in the signed-in web viewer.
Troubleshooting
My client says "No MCP server named limn found"
Check the client-specific configuration above, then restart the client. In Codex, run codex mcp list or use /mcp to verify the server is enabled.
My agent sees 0 threads on a file I know has threads
The thread must be on the exact repository and file path the agent is reading. Check both values in the Limn viewer.
I get a 401 Unauthorized error
Your API key may be malformed or revoked. Go to Settings → API, revoke the affected key if it is still listed, and create a replacement.