Publish a docs site for your developer tool with Thally

I wrote the docs for person-mcp, a small MCP server that gives an AI agent a memory of the people you meet, and published them with Thally. The result is live at person-mcp.thally.app, and the source is at github.com/nicolasarnedo99/person-mcp-docs. This post is the path I took, so you can do the same for your own tool in under an hour.

What you need

• Node.js 22.14 or newer (Thally also supports 20.19+ and 24+)
• A GitHub account and the gh CLI, logged in
• A Thally Cloud account at app.thally.io. The free plan covers one managed site
• A tool to document, and the ability to run it. That second part matters more than it sounds, as you will see below

1. Scaffold the project

Thally’s quickstart leads with Thally Cloud creating the repository for you. I used the CLI instead, for a reason I explain in the obstacles section:

npx create-thally-docs person-mcp-docs --yes --install
cd person-mcp-docs

--yes accepts the defaults and --install installs dependencies in the same step. Wait for the command to finish completely before you touch any files: it creates its initial git commit at the very end, after the install.

You now own three things:

Path	What it holds
src/content/	Your pages, as MDX
docs.json	Navigation and features
src/data/site.ts	Product name, description, repository link

Everything else is the Thally runtime. Leave it alone; framework updates arrive as pull requests.

2. Configure the site

Set the identity in src/data/site.ts:

name: 'person-mcp',
description: 'Relationship memory for your AI agent: an MCP server that remembers the people you meet.',
repoUrl: 'https://github.com/nicolasarnedo99/person-mcp',

Then replace the starter navigation in docs.json with the pages you actually plan to write. For a small tool, four is enough:

"tabs": [
  { "tab": "Get started", "groups": [{ "group": "Get started", "pages": ["introduction", "quickstart"] }] },
  { "tab": "Guides", "groups": [{ "group": "Use person-mcp", "pages": ["guides/prep-before-a-call"] }] },
  { "tab": "Reference", "groups": [{ "group": "Reference", "pages": ["reference/tools"] }] },
  { "tab": "Changelog", "href": "/changelog" }
]

The starter ships with an API Reference tab, a components showcase and three example guides. Delete the pages you will not use from src/content/ so nothing is orphaned.

3. Write the content

Each page is an MDX file with a title and a description in its frontmatter. I wrote four:

• Introduction: what the tool does, who it is for, and a table of its five tools.
• Quickstart: clone, install, start, connect to Claude Code, ask a first question. It uses Thally’s <Steps> component, so each step reads as one action with its expected result.
• A practical guide: the import, log and recall loop the tool exists for, with real requests and responses, and <Accordion> blocks for troubleshooting.
• A tool reference: every parameter of every tool.

The rule I held myself to: every command and every response on the site comes from running the tool, not from its README. I started the server locally and called each tool with the exact payloads shown in the guide, then pasted the real output.

4. Check and build

npx --yes @thallylabs/cli@latest check
npm run build

check lints the content and navigation. build proves the site compiles, and its output shows what you get for free: llms.txt, llms-full.txt, a skill.md for agents and an MCP endpoint, alongside the human pages.

To preview while you write, npm run dev serves the site at http://localhost:3040.

5. Publish

Push the project to a GitHub repository you created yourself:

gh repo create person-mcp-docs --public
git remote add origin git@github.com:<you>/person-mcp-docs.git
git add -A && git commit -m "docs: document person-mcp"
git push -u origin main

Then in Thally Cloud:

1. Select Create a site, and enter a name and a thally.app address.
2. At Docs source, choose Use an existing repository.
3. Install the Thally GitHub App with Only select repositories, and pick the docs repository.
4. Skip Product sources for now, review, and select Publish site.

When the workspace Home page shows the site as Live, open the thally.app URL and check every page. From then on, a push to main redeploys it.

Obstacles and how I got past them

The recommended path wants access to all your repositories. When Thally Cloud creates the docs repository for you, its GitHub App needs All repositories access on your account so it can initialise the new one. My account has private repositories that have nothing to do with docs, so I did not want to grant that. The fix was the developer path above: scaffold with the CLI, create the repository myself, and grant the app access to that one repository.

The scaffold commits after it installs. I started editing docs.json while --install was still running, and the CLI’s initial commit picked up my half-finished changes. Let the command finish before you open the files.

The README was wrong, and only running the tool showed it. person-mcp’s README listed four tools; the server exposes five. My first draft of the guide also passed entry to log-interaction, which the server rejected with a validation error, because the parameter is note. Running every example against the real server caught both. Thally’s own docs make the same point: treat the product as the source of truth, not the notes about it.

Where to go next

Thally can also watch your product repository and open documentation pull requests when the code changes (it calls this Track). For a tool that changes as fast as an MCP server, that is the next thing I would turn on.