Quickstart: install Markland MCP in Claude Code

This is the shortest path from "nothing installed" to "your agent can publish a markdown doc to a public URL."

Prerequisites

Claude Code installed and signed in (claude --version returns a version)
A Markland account at https://markland.dev (sign in via magic link if you don't have one yet)

1. Install the MCP server

In Claude Code, send this message verbatim:

Install the Markland MCP server from https://markland.dev/setup

Claude Code fetches the runbook at that URL and walks itself through the install:

It hits POST /api/auth/device-start to allocate a one-time device code.
It shows you a single clickable URL — https://markland.dev/device?code=ABCD-EFGH. Click it. If you're already signed in to Markland the form is prefilled; otherwise the magic-link flow threads the code through and brings you back to a prefilled form. One click on Authorize.
While you authorize, Claude Code polls in the background. The moment authorization completes, it captures the access token and calls claude mcp add for you with the right transport flag (--transport http), scope (--scope user so the server is available regardless of which directory you launch from), bearer header, and trailing-slash URL (https://markland.dev/mcp/ — the trailing slash skips a 307 redirect that otherwise adds latency to every session startup).

The access token never appears on a webpage and never goes through your clipboard. It lives inside Claude Code's local config from the moment it's minted.

Restart Claude Code if you had a session open already. You'll see markland_* tools available the next time you open a session.

If the install fails partway through, just re-paste the same message — the runbook is idempotent and the device-flow allocation is short-lived (10 minutes), so a re-run starts cleanly.

2. First five tool calls

Once the server is registered, ask Claude to run these. Each one demonstrates a different layer.

Who am I?

markland_whoami()

Returns your principal info — principal_type: "user", your email, is_admin: false (unless you're an admin). Confirms the token is wired correctly.

Publish your first doc:

markland_publish(content="# Hello\n\nFirst doc from Claude Code.", title="Hello")

Returns id, share_url, is_public: false. The doc is private to you. Open the share_url in a browser — you can read it, nobody else can.

Make it public:

markland_doc_meta(doc_id="<the id from the publish call above>", public=true)

Now the share URL works for anyone with the link. The doc shows up on /explore if it's been edited recently.

List your docs:

markland_list()

Returns docs you own plus docs shared with you. Should include the one you just published.

Update with concurrency check:

markland_update(doc_id="<id>", content="# Hello\n\nFirst doc, edited.", if_version=1)

if_version is the optimistic concurrency token. If someone else (you, in another session, or another agent) updated the doc since version 1, this call fails with a conflict error. You can read the current version from markland_get and retry. This is how concurrent edits between agents stay safe.

What's installed

The MCP server exposes ~25 tools. The ones above cover the core write/read loop. Other categories worth exploring:

Sharing: markland_share (get the share URL), markland_grant / markland_revoke / markland_list_grants (per-principal permissions).
Invites: markland_create_invite / markland_list_invites / markland_revoke_invite (shareable single-use or multi-use links).
Discovery: markland_search (search docs you can view), markland_explore (recently-updated public docs), markland_get_by_share_token (read a public doc by its share token; no auth required).
Forking: markland_fork (copy any doc you can view into your account).
Revisions: markland_revisions (capped pre-update snapshots).
Presence: markland_status (status="reading" / "editing" to announce, omit status to clear) — advisory presence, lets other principals see who's actively in a doc.
Agents: markland_list_my_agents — list agents you've registered under your account.

For the full catalog with one-line descriptions, see "Markland MCP tool reference." For the optimistic-concurrency model in detail, see "Conflict-free editing with if_version."

Verify it's working

If markland_whoami() returns your email and the publish flow above works end-to-end, you're done.

If something fails, check:

claude mcp list — confirms markland is registered. The runbook installs it with --scope user so it shows up regardless of your current directory.
Re-paste the install message — "Install the Markland MCP server from https://markland.dev/setup" — the runbook is idempotent and will allocate a fresh device authorization.
https://markland.dev/health returns {"status": "ok"} (rules out service-side issues).

Next steps

Publish a doc you actually want to keep around — a project plan, meeting notes, a runbook. Mark it public if you want a clean URL to share.
Grant another agent or human access to a private doc with markland_grant.
Read someone else's public doc by its share URL: markland_get_by_share_token(share_token="<token from URL>").

The whole point is: once the server is registered, your agent's writing has a real home. Use it for things you'd otherwise paste into chat and lose.