Connect Markovo.

1. Try a fileUse the homepage uploader to confirm output quality.
2. Create an accountSign in with Google, GitHub, or a verified email address.
3. Use your plan limitFree starts with one API key; paid plans add capacity, batches, concurrency, and retention.
4. Generate a keyCopy the key once and store it in your server environment.
5. Open Developer SetupUse the account app snippets for API, CLI, and MCP configuration.
6. Install clientsInstall the verified, immutable Markovo client commit when CLI or MCP should upload local files through the product API.
7. AutomateCall API, CLI, or MCP depending on who operates the workflow.

Keep production keys in server or agent secrets. Never place API keys in browser code.

export MARKOVO_API_KEY="mk_live_..."

curl -X POST https://markovo.net/v1/convert \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -F "file=@paper.pdf" \
  -F "file=@appendix.pdf" \
  -F "mode=fast" \
  -F "max_credits=30"

The account app shows the same snippets after sign-in. The CLI and MCP package requires Python 3.10 or newer. Replace placeholders with your API key and keep secrets in backend or agent environments.

export MARKOVO_API_KEY="mk_live_..."
export MARKOVO_MCP_ROOT="/path/to/dedicated/project"

python -m pip install "markovo==0.1.1"
	markovo doctor --json
	markovo convert paper.pdf --out runs/paper --mode fast --max-credits 30
	markovo usage

{
  "mcpServers": {
    "markovo": {
      "command": "markovo-mcp",
      "env": {
        "MARKOVO_API_KEY": "${MARKOVO_API_KEY}",
        "MARKOVO_MCP_ROOT": "/path/to/dedicated/project"
      }
    }
  }
}

Use multipart upload for one or more supported files, then poll each returned job until it succeeds. Put API keys in backend environments, not browser code.

curl -X POST https://markovo.net/v1/convert \
  -H "Authorization: Bearer mk_live_..." \
  -F "file=@paper.pdf" \
  -F "file=@appendix.pdf" \
  -F "capability_id=pdf-to-markdown" \
  -F "mode=fast" \
  -F "max_credits=30"

The response includes jobs[]. For backwards compatibility, job_id points to the first queued job.

curl https://markovo.net/v1/jobs/{job_id} \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}"

curl -L "https://markovo.net/v1/jobs/{job_id}/download?format=md" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -o output.md

Recommended formula enhancement for PDFs

Web signed-in PDF conversion defaults Formula enhancement on. Guests see an unchecked Signed-in Beta option; choosing it opens sign-in instead of silently changing the request to standard. REST, CLI, and MCP default to standard and opt in only with layout_fidelity=formula. Markovo first checks for formula regions: if none are found, it uses standard conversion and adds 0 formula Credits; if regions are found, the estimate shows the region count and price before conversion starts. The normal PDF charge remains and each detected region adds 700 credit_units (0.7 Credit). Compare every equation with the original PDF because symbol, variable, root, subscript, or superscript errors remain possible.

curl -X POST https://markovo.net/v1/estimates \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -F "file=@equations.pdf" \
  -F "capability_id=pdf-to-markdown" \
  -F "layout_fidelity=formula"

Create a key inside the account app after signing in. Plaintext is shown once.

• Header: Authorization: Bearer mk_live_...
• Scope: markovo:convert
• Usage is settled against the single conversion.credits balance.
• Login capability: GET /v1/account/auth/providers reports enabled OAuth providers and email-code signup state.

Product API client. The public CLI is pinned to https://markovo.net, loads MARKOVO_API_KEY only from the environment, then polls and downloads the result bundle.

python -m pip install "markovo==0.1.1"
	export MARKOVO_API_KEY="mk_live_..."

markovo convert paper.pdf --out runs/paper --mode fast --max-credits 30
	markovo convert equations.pdf --out runs/equations --layout-fidelity formula --max-credits 30
	markovo usage
	markovo billing  # returns the secure browser billing URL

Customer workflows use the account-metered markovo convert command, so browser, API, CLI, and MCP activity appears in the same history. If --max-credits is omitted, CLI uses a 15-Credit convenience safety ceiling. Markovo obtains an estimate internally before job creation and rejects work estimated above that ceiling; the client does not pause for user confirmation. Set an explicit bound for deliberate automation. CLI and MCP callers must explicitly choose layout_fidelity=formula. Detected formula regions render as LaTeX; compare every equation with the original PDF.

Verify the current filename and SHA-256 in the client manifest before managed deployment.

Remote MCP with OAuth

Add https://markovo.net/mcp to an MCP client that supports Streamable HTTP and OAuth. The client discovers Markovo's OAuth 2.1 endpoints, opens the normal account sign-in and an explicit consent screen, and receives only the approved markovo:read and markovo:convert scopes. You do not create or paste an API key for this connection.

The remote server exposes nine focused tools for capabilities, Credit usage, owned jobs, public-HTTPS URL conversion, verified result images, short-lived asset links, and billing help. It has no local-file, arbitrary network, shell, credential, payment, or administrator tool. Every URL conversion requires a positive max_credit_units ceiling. Markovo never tops up Credits, opens Checkout, or changes a plan automatically; low-balance responses point the account owner to Billing. Read the copy-ready Remote MCP guide.

Remote MCP URL: https://markovo.net/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.1 Authorization Code + PKCE

Local stdio MCP

The customer-only MCP package exposes exactly the following account-metered tools over stdio. It contains no local conversion engine. When max_credits is omitted, it uses the same 15-Credit convenience safety ceiling. Markovo obtains an estimate internally before job creation and rejects work estimated above that ceiling; the client does not pause for user confirmation. Set an explicit bound for deliberate automation. REST and direct clients remain explicit. Web signed-in PDF conversion defaults Formula enhancement on; REST, CLI, and MCP default to standard and opt in with layout_fidelity=formula.

• markovo_convert
• markovo_convert_url
• markovo_job_status
• markovo_job_assets
• markovo_asset_url
• markovo_asset_revoke
• markovo_usage
• markovo_capabilities
• markovo_billing
• markovo_bundle_verify
• markovo_doctor

markovo_convert reads and writes local filesystem paths only inside the required MARKOVO_MCP_ROOT. Missing roots, parent-directory escapes, absolute paths outside the root, and symlink escapes fail closed. If an agent has no mounted disk or cannot expose the file inside that dedicated root, use REST multipart upload instead. API keys and the service origin are never MCP tool arguments. For Word, keep the runtime capability ID explicit:

{
  "input_path": "/absolute/path/report.docx",
  "out_dir": "/absolute/path/runs/report",
  "capability_id": "docx-to-markdown",
  "max_credits": 10
}

Asset grant URLs are bearer capabilities that last 60–600 seconds. An expired or revoked grant URL returns not found; request a new grant only while the owned job and asset still exist, and never persist the URL.

python -m pip install "markovo==0.1.1"
	export MARKOVO_API_KEY="mk_live_..."
	export MARKOVO_MCP_ROOT="/path/to/dedicated/project"
	markovo-mcp
	# or: markovo mcp

{
  "mcpServers": {
    "markovo": {
      "command": "markovo-mcp",
      "env": {
        "MARKOVO_API_KEY": "${MARKOVO_API_KEY}",
        "MARKOVO_MCP_ROOT": "/path/to/dedicated/project"
      }
    }
  }
}

PDF is live. Public HTTPS URL import, DOCX, PPTX, XLSX, TXT, Markdown, JSON, XML, HTML, CSV, PNG, JPEG, WebP, TIFF, BMP, EPUB, Notion Export ZIP, supported audio, and supported video are authenticated Beta capabilities. They use the same Credits, ownership, History, API, CLI, MCP, and artifact contract. Other formats remain Planned until their quality and cost gates pass.

• Anonymous users can preview one ordered queue per UTC day, with the Free account file boundary of 25 MB and 50 source units per file. The continuous prefix is capped at 5 estimated Credits, and Download requires account settlement.
• Signed-in Free users receive 100 Credits per UTC calendar month, one active API key, and 5 conversions per UTC day, one file at a time, with 25 MB and 50 pages per file.
• Plus is $8/month with 2,000 Credits, API keys and batches up to 20 files, with 50 MB / 500 pages per file. Paid use continues while Credits remain; short traffic bursts are rate limited for platform safety.
• Pro is $19/month with 6,000 Credits, API keys, two concurrent jobs, and batches up to 50 files, with 50 MB / 500 pages per file. There is no fixed daily conversion count.
• Credit packs add to the current account and expire after 365 days. They do not change the tier's batch or concurrency limits; while an unexpired purchased balance remains, there is no fixed daily conversion count.
• Subscriptions use conversion.credits, roll over at most one month, and cap the balance at twice the monthly grant.
• Anonymous and Free results expire after one hour; Plus after 7 days; Pro after 30 days. Source files are deleted after processing.
• Jobs estimated above 12 minutes are rejected before processing.

Public API errors include a stable code, a human-readable message, a per-response request_id, a retryable boolean, and a documentation URL. The same request ID is returned in the x-request-id response header.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Not enough credits.",
    "request_id": "…",
    "retryable": false,
    "docs_url": "https://markovo.net/docs#errors"
  }
}

Retry only when retryable is true. For quota, ownership, validation, or Credit-ceiling errors, follow the returned action or fix the request instead of looping.