Set up the tl;dv Studio connector

You are an assistant, and a person asked you to connect them to tl;dv Studio. Follow the steps below one at a time and tell the person what to do at each step. This page is public and holds no secret.

What tl;dv Studio is

tl;dv Studio is where authors write blog posts for tldv.io with an assistant. The author drafts, previews and submits an article; the team reviews it and promotes it to the site. The connector gives you the tools to do that work for the person. It is an MCP server at this URL:

https://website-studio.tldv.tech/_mcp

Before you start

• The person needs an account. Accounts come from the team's list, so an email that is not on it cannot sign in. If the person has no account, tell them to ask the team.
• The account needs an author linked. An account with no author can sign in to previews but cannot connect an app: the sign-in ends on a page called "No author linked". If the person sees it, tell them to ask the team to link an author.

Add the connector

claude.ai (web, desktop and mobile)

1. Tell the person to open Settings → Connectors → Add custom connector.
2. Name: tl;dv Studio. URL: https://website-studio.tldv.tech/_mcp
3. Tell them to press Connect. A browser page called "Connect an app" opens: go on with Sign-in below.

Claude Code

1. Run this in a terminal (the person can run it for you): claude mcp add --transport http tldv-studio https://website-studio.tldv.tech/_mcp
2. In Claude Code, type /mcp, choose tldv-studio and sign in. A browser page called "Connect an app" opens: go on with Sign-in below.

Sign-in

1. The "Connect an app" page names the app asking and the host it returns to (claude.ai for claude.ai). Tell the person to check that it is the app they are using.
2. The person types their own email into the page and presses Email me a code.
3. A code arrives by email. It works for 10 minutes, once. The person types it into that sign-in page and presses Continue.
4. The browser goes back to the app and the connector shows as connected.

Never ask the person for the emailed code. Tell them never to paste it into a chat. It belongs in the sign-in page only. You do not need it.

No code after a minute or two: tell the person to check their spam folder, then press Send a new code on the code page. From the second code the page also offers I still have no code: it tells the team, and someone reaches out. Do not try to work around a missing code.

Check that it works

Call the whoami tool. It answers with the account's email, its role (author or team) and its author node. If it answers, the connector works. A good next call is list_taxonomy.

Troubleshooting

• "Request expired": the sign-in request ran out. Start again from the app (press Connect again, or /mcp in Claude Code).
• "That code did not work": a code works once and for 10 minutes. Press Send a new code and use the newest email.
• The app is refused when it registers: its callback host is not on the team's list. The team adds the host with the client_hosts tool. Tell the person to ask the team.
• "No author linked": see Before you start. The team must link an author to the account.
• A 401 from the connector after about a month: the refresh token ran out. Reconnect: press Connect again (claude.ai) or sign in again from /mcp (Claude Code).
• A tool answers with an error code that starts with E_: read the message after it and tell the person. E_FORBIDDEN means this account may not do that.

Tools

This list is generated from the tools the connector serves. Try whoami first.

• whoami: Who the signed-in account is: email, role and linked author node.
• list_taxonomy: The existing authors, categories and article slugs, so the names you use are valid ones.
• create_article: Start a new blog article as a draft under your byline. Returns its id and a preview link. Authors cannot name another byline.
• start_update: Open a draft of a published article from its current version on main. A Preserved HTML post is converted to MDX first. One open draft or candidate per article.
• abandon_article: Throw away your own unsubmitted draft: removes its worktree, preview and record, and frees one of your five draft slots. A submitted draft is refused with its merge request link.
• save_article: Save the body and/or frontmatter of your open draft, run the checks and render the preview. Returns the check results and the preview link.
• add_image: Add an image to your draft: pass url (the service fetches it), or size (and contentType) to start a multipart upload and get presigned part URLs, then uploadId to complete it (abort: true cancels). Returns the path to use in the body.
• get_status: The state of an article (draft, candidate, translating, in_mr, merged, live), its checks, preview and MR links. While translating it shows done/total languages and the failures. Without an article: all of yours.
• submit: Your OK: freezes the source language and answers at once with state translating. The service then writes every other language itself, one after another, pushes the branch, opens the merge request and posts its report there and to Slack. Needs a passing save first. Refused while the article is already translating; after a first run that stopped before the merge request opened, it tries again.
• retranslate: On an article whose merge request is open: rewrites the languages that are stale (the source changed after they were written) or failed, from the branch as it stands, and pushes. Languages a person pinned (staysFixed) are never rewritten. Answers at once with state translating; refused on a merged or closed merge request.

Tools for the team only

An author who calls one of these is refused.

• client_hosts: the hosts an OAuth client may return to (Claude, ChatGPT). action list shows them; allow adds a host; remove drops one. A client registering with any other https host is refused.
• reassign_article: move the byline of an open draft to another author node, and with it the ownership.