MCP Server

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. Instead of hardcoding integrations, agents discover what tools are available, what parameters they accept, and how to call them — all at runtime.

AILANG Parse ships as a native MCP server. The hosted connector exposes 7 tools: parse, convert, edit, formats, estimate, account and feedback. Claude, ChatGPT, Codex, Cursor, VS Code and any MCP-compatible agent can discover and call them. Office and text formats are parsed deterministically, PDFs with pdftotext (AI only when you ask for it, for scans), and images with pluggable AI.

Connect from Claude, ChatGPT or Codex

The quickest way to use AILANG Parse from an AI assistant is the hosted connector, which signs in with OAuth so you never copy an API key:

https://docparse.ailang.sunholo.com/mcp/connect/

Setup for each app, signing in, sending documents, download links, revoking access and troubleshooting: Connect from Claude, ChatGPT or Codex. The AILANG Parse plugin installs the connector and the skill together in Claude Code and Codex.

Two ways to sign in

The hosted server has two MCP endpoints. They run the same tools on the same account; they differ in how the client signs in.

Either way the result is an ordinary dp_ key on your account with the same quota. Keys created through OAuth are labelled oauth: <app> on your dashboard and expire after 24 hours (the client renews them). Outside MCP — the REST API, the SDKs, the skill's scripts — you use a dp_ key from the dashboard or the device flow.

Quick Start

Local — stdio (recommended)

For Claude Desktop, Cursor, and VS Code. The agent launches the server automatically:

# No manual server start needed — the MCP client launches this:
ailang serve-api --mcp --routes-only --caps IO,FS,Env docparse/

Local — HTTP

For MCP clients that connect over HTTP:

# Start with MCP HTTP endpoint at /mcp/
ailang serve-api --mcp-http --routes-only --caps IO,FS,Env --port 8080 docparse/

# Test it
curl -X POST http://localhost:8080/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Hosted

No local install required. Connect to the hosted endpoint. Discovery works without a key; send your key as a header (or as the apiKey argument; see Agent Auth Flow):

curl -X POST https://docparse.ailang.sunholo.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dp_your_api_key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

With AI parsing

To parse PDFs, images, audio, or video, add AI capabilities:

# Add AI model for non-Office formats
ailang serve-api --mcp --routes-only \
  --caps IO,FS,Env,AI,Net --ai gemini-2.5-flash docparse/

Available Tools

The hosted connector exposes 7 tools; the agent surface /mcp/ adds the two device-flow tools. Agents discover them automatically from tools/list. On the hosted service, give a tool your document in one of three ways: the document itself as content + filename (text, or base64 with contentEncoding="base64" for binary files), a public https:// URL, or a sample id.

Core Tools (local + hosted)

Hosted-Only Tools

These tools are available when connecting to the hosted service at docparse.ailang.sunholo.com. They let agents edit documents, check the account, send feedback and, on the agent surface only, sign in with the device flow.

Each tool has named parameters with JSON Schema types. Agents receive full schemas via tools/list — no hardcoding required.

Device flow on the agent surface

Clients that can open a browser should use the OAuth connector /mcp/connect/ (above), where none of this is needed. On the agent surface /mcp/, an agent without a key signs in like this:

1. Agent calls mcpParse → receives AUTH_REQUIRED error with suggested_fix
2. Agent calls mcpAuth(label: "claude-desktop") → receives verification URL + user code
3. Agent tells the human: "Open this URL and sign in. Your code is WXYZ-5678."
4. Agent calls mcpAuthPoll(deviceCode) every 5s → receives api_key + tier
5. Agent sends the key as a header (preferred) or apiKey in subsequent calls

Prefer a header. Clients that can send a fixed header can skip the device flow. Generate a key on the API page and send it as Authorization: Bearer dp_… (or X-API-Key). The key then never enters the model's context, and apiKey can be left out of every call. An explicit apiKey argument still works and takes precedence.

Install from the MCP Registry

AILANG Parse is listed in the official MCP Registry as io.github.sunholo-data/parse. Registry-aware clients can discover and install it without you copying any JSON snippets.

How to install via the registry

• Claude Code: claude mcp add io.github.sunholo-data/parse — resolves the entry, picks the best available transport (PyPI / npm / hosted HTTP), and writes the config for you.
• Cursor / VS Code with MCP extension: open the MCP server browser and search for parse or sunholo. Click install — the client populates .cursor/mcp.json or .vscode/settings.json automatically.
• Any registry-aware client: point it at io.github.sunholo-data/parse. The listing exposes both packages (npm + PyPI stdio bridges) and a remote (hosted Streamable HTTP at docparse.ailang.sunholo.com/mcp/); the client picks whichever it supports.

Inspect the live entry directly:

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=parse" \
  | jq '[.servers[] | select(.server.name == "io.github.sunholo-data/parse")]'

Manual Configuration

Claude Desktop (hosted — recommended)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Pick whichever runtime you have installed — all three SDKs ship the same stdio bridge.

Node.js ≥ 18:

{
  "mcpServers": {
    "ailang-parse": {
      "command": "npx",
      "args": ["-y", "@ailang/parse", "mcp"]
    }
  }
}

Python ≥ 3.8 (via uv):

{
  "mcpServers": {
    "ailang-parse": {
      "command": "uvx",
      "args": ["ailang-parse", "mcp"]
    }
  }
}

Go (install once, run from PATH):

go install github.com/sunholo-data/ailang-parse-go/cmd/ailang-parse@latest

{
  "mcpServers": {
    "ailang-parse": {
      "command": "ailang-parse",
      "args": ["mcp"]
    }
  }
}

All three run the same stdio MCP bridge to the hosted API. No API key needed upfront — the agent handles device auth automatically.

Claude Desktop (local)

For local-only parsing without the hosted API, add to claude_desktop_config.json:

{
  "mcpServers": {
    "ailang-parse": {
      "command": "ailang",
      "args": ["serve-api", "--mcp", "--routes-only", "--caps", "IO,FS,Env", "docparse/"],
      "cwd": "/path/to/ailang-parse"
    }
  }
}

Claude Code

Install the plugin for automatic MCP registration — run both inside Claude Code:

# Run both inside Claude Code
/plugin marketplace add sunholo-data/docparse-skill
/plugin install ailang-parse@ailang-parse-marketplace

Or add to .mcp.json (project or global):

{
  "mcpServers": {
    "ailang-parse": {
      "url": "https://docparse.ailang.sunholo.com/mcp/"
    }
  }
}

For local-only mode, use the command form instead:

{
  "mcpServers": {
    "ailang-parse": {
      "command": "ailang",
      "args": ["serve-api", "--mcp", "--routes-only", "--caps", "IO,FS,Env", "docparse/"],
      "cwd": "/path/to/ailang-parse"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ailang-parse": {
      "command": "ailang",
      "args": ["serve-api", "--mcp", "--routes-only", "--caps", "IO,FS,Env", "docparse/"],
      "cwd": "/path/to/ailang-parse"
    }
  }
}

VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "ailang-parse": {
        "command": "ailang",
        "args": ["serve-api", "--mcp", "--routes-only", "--caps", "IO,FS,Env", "docparse/"],
        "cwd": "/path/to/ailang-parse"
      }
    }
  }
}

Tool Discovery

AILANG Parse follows an agent-first design. Three discovery mechanisms:

MCP tools/list

MCP clients call tools/list and receive full JSON Schema input definitions automatically — no configuration needed once the server is connected. On the connector /mcp/connect/ it returns 7 tools: mcpParse, mcpConvert, editDocument, mcpFormats, mcpEstimate, mcpAccount and submit_feedback; the agent surface /mcp/ adds mcpAuth and mcpAuthPoll. Large-file uploads (getUploadUrl) are REST-only.

mcpFormats (recommended first call)

Agents should call mcpFormats first. It returns 17 input formats, 9 output formats, 26 test samples, and how to send a document. Plans and prices are on the pricing page and GET /api/v1/pricing.

REST /api/v1/tools

Non-MCP clients can fetch tool definitions via REST:

curl -s https://docparse.ailang.sunholo.com/api/v1/tools | jq '.tools | length'
# 7

curl -s https://docparse.ailang.sunholo.com/api/v1/tools | jq '.tools[0].name'
# "mcpParse"

With Claude Code

Two options for document parsing in Claude Code:

Option 1: MCP Server (recommended)

Add the config above to your settings. Claude discovers the tools automatically and uses them when you ask it to parse or convert documents.

Option 2: Claude Code Skill

Install the AILANG Parse skill for zero-config local parsing without running a separate server. See the Claude Code integration page.

With Other Agents

Any MCP Client

Any client that speaks MCP can connect via stdio or HTTP. The server advertises its tools, resources, and capabilities via the standard MCP protocol.

REST API

Non-MCP agents can call the same tools via the REST API:

# Python — parse with the hosted API
import requests

response = requests.post(
    "https://docparse.ailang.sunholo.com/api/v1/parse",
    json={"filepath": "report.docx", "outputFormat": "markdown", "apiKey": "dp_YOUR_KEY"}
)
markdown = response.json()["result"]

# Or use the Python SDK
from ailang_parse import DocParse
client = DocParse(api_key="dp_YOUR_KEY")
result = client.parse("report.docx", output_format="markdown")

LangChain / LlamaIndex

Register AILANG Parse as a tool in your agent chain:

from langchain.tools import StructuredTool

ailang_parse = StructuredTool.from_function(
    func=lambda filepath, output_format="blocks": requests.post(
        "https://docparse.ailang.sunholo.com/api/v1/parse",
        headers={"X-API-Key": "dp_YOUR_KEY"},
        files={"filepath": open(filepath, "rb")},  # upload: the API never reads a path on your disk
        data={"outputFormat": output_format},
    ).json()["result"],
    name="ailang_parse",
    description="Parse a document into structured blocks, markdown, or HTML"
)