Docs

Codex Markdown Sharing Workflow

Connect mkdshare to OpenAI Codex and other coding agents. Publish implementation plans, handoffs, and reports as shareable links without leaving the agent session.

How Codex connects to mkdshare

Codex supports MCP servers via HTTP. Point it at https://mkdshare.dev/mcp with your Bearer token and Codex can publish, read, and annotate markdown documents in any task.

Step 1 — Get your API token

Sign up with Google, then visit mkdshare.dev/api-access to copy your token.

Step 2 — Add mkdshare to your Codex config

In your codex.yaml (or equivalent config), add mkdshare under mcpServers: 

mcpServers:
  mkdshare:
    type: http
    url: https://mkdshare.dev/mcp
    headers:
      Authorization: Bearer <your-token>

Codex picks up MCP servers at session start. No restart required after editing the config.

Step 3 — Verify the connection

Start a Codex session and ask it to list your documents:

Use mkdshare to list my documents.

Available tools

create_document Publish a markdown doc and get a shareable URL. Supports visibility, expiry, and email allowlists.
get_document Read the full content of any document you have access to.
update_document Edit the title, content, or access settings of a document you own.
list_documents List all documents you own.
create_annotation Add an inline comment anchored to a specific passage of text.
list_annotations List all inline comments on a document.

Example workflows

Write a markdown implementation plan for this feature and publish it on mkdshare restricted to @mycompany.com. Return the link.
Publish a markdown handoff summarizing what was built, the decisions made, and what's left to do.
Read the annotations on mkdshare document abc123 and create GitHub issues for each requested change.
Create a progress report in markdown and publish it on mkdshare with a 7-day expiry.

Using the REST API instead

If your agent environment supports HTTP calls but not MCP, use the REST API with the same Bearer token: 

curl -s https://mkdshare.dev/api/documents \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"document": {"title": "Handoff", "content": "# Done\n\nShipped.", "visibility": "public"}}'

Full REST API reference: docs/api

Troubleshooting

Tools not available in session

Make sure the type is http and the URL has no trailing slash. Verify the config was saved before starting the session.

401 Unauthorized

Your token is missing or incorrect. Get a fresh token at mkdshare.dev/api-access.

Create a free account to get your API token.