oxml-mcp

oxml-mcp

A Model Context Protocol server that lets a model query XML instead of reading it — powered by oxml , with zero unsafe code.

---

Contents

Getting started

• Why a model wants this — the problem an XML tool solves for an LLM
• Install — Cargo, from source
• Transports — stdio, streamable HTTP, SSE
• Quick Start — three lines, no client required
• Configure — Claude Desktop, and any MCP client

The oxml ecosystem

• The oxml ecosystem — seven crates, one version

Reference

• Tools — xml_query, xml_validate, xml_check, xml_inspect, xml_format
• Protocol — MCP 2025-11-25 and 2026-07-28, and the two kinds of failure
• Errors — the two kinds, and which is which
• Design — why five tools, and why documents are strings
• Capabilities in 0.0.16 — release inventory
• Ecosystem comparison — how this compares to the alternatives
• Benchmarks — latency per request, measured in pairs

Practical

• Examples — a full session, and every error path
• When not to use oxml-mcp
• FAQ
• Development
• Security
• Roadmap
• Documentation
• Acknowledgements
• License

---

Why a model wants this

A client can supply XML directly as a tool argument and put only the selected results into a model prompt. count(//record) returns a count computed by the parser rather than an estimate from a pasted fragment.

The server accepts XML strings up to its strict 8 MiB source limit; it does not open paths or fetch URLs. A model constructing the complete tool argument itself still needs the XML text. The HTTP transport has its own, tighter SDK request-body limit.

The secondary argument is arithmetic. A model asked to count elements in a document it can see will approximate. xml_query with count(//record) will not.

Install

cargo install oxml-mcp --version 0.0.16 --locked

Without a Rust toolchain, the same binary ships as an image on GHCR (the MCP registry entry points at it):

docker run --rm -i ghcr.io/sebastienrousseau/oxml-mcp:0.0.16

Transports

One binary, three ways to reach it. Every server in the suite takes the same flags.

Streamable HTTP serves both current revisions on the one endpoint: a client that sends initialize gets a session and an Mcp-Session-Id; a client that names 2026-07-28 in each request's _meta is served statelessly, with server/discover in place of the handshake. Responses stream as server-sent events, and GET /mcp opens the server-to-client stream. The SSE transport is the older one, for hosts that still expect an endpoint event and a message URL.

The HTTP transports bind the loopback interface unless --host says otherwise, and they do not authenticate. Put the server behind a gateway you trust before binding a routable address. They refuse a foreign Host or a non-local Origin with 403, and --max-sessions (64 by default) caps how many sessions they hold at once; see doc/PROTOCOL.md. --version and --help do what they say.

Quick Start

The server speaks JSON-RPC 2.0 over stdio, so three lines are enough to see it work — the handshake, then a call — and no client is required:

printf '%s\n' \

'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"me","version":"0"}}}' \ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \ '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"xml_query","arguments":{"xml":" Dune ","xpath":"//title"}}}' \ | oxml-mcp | tail -n 1

{"jsonrpc":"2.0","id":2,"result":{"resultType":"complete","content":[{"type":"text","text":"Dune"}],"structuredContent":{"count":1,"values":["Dune"]},"isError":false}}

For day-to-day use you want a client to do that for you — see Configure.

Configure

Add it to your MCP client's server list. For Claude Desktop, in claude_desktop_config.json:

{

"mcpServers": { "oxml": { "command": "oxml-mcp" } } }

For Claude Code:

claude mcp add oxml -- oxml-mcp

Without arguments the server speaks JSON-RPC 2.0 over stdin and stdout, one message per line, which is what these clients expect. A client that connects over HTTP instead points at a server started with --transport streamable-http — see Transports. There is no configuration file.

The oxml ecosystem

All seven ship one version number, in steps of 0.0.1.

Tools

xml_query

Evaluate an XPath 1.0 expression and return the matching values.

{"name":"xml_query","arguments":{"xml":"<r><t>Dune</t><t>Germinal</t></r>","xpath":"//t"}}

Dune

Germinal

One value per line. Expressions returning a number, string or boolean return that value directly, so count(//t) gives 2. Every tool also returns its answer as structuredContent, against the outputSchema it advertises — here {"count": 2, "values": ["Dune", "Germinal"]}.

xml_inspect

Summarise a document's shape: root element, maximum depth, every element name with its count, and the namespaces it uses.

{"name":"xml_inspect","arguments":{"xml":"<r><t>x</t></r>"}}

Root element: r

Maximum depth: 3 Elements: r: 1 t: 1

Call this first. A model that knows the element names can write a query that works; one that guesses writes //item against a document whose elements are called record.

xml_check

Report whether a document is well-formed, with a line and column if it is not.

{"name":"xml_check","arguments":{"xml":"<a/>"}}

The document is well-formed (2 nodes).

xml_validate

Validate against an XML Schema, returning every violation with the path to the element it concerns.

xml_format

Format an XML document with configurable indentation (spaces) and empty element style, or minify it.

{"name":"xml_format","arguments":{"xml":"<root><item/></root>","indent":2}}

Protocol

MCP over JSON-RPC 2.0, implemented by rmcp, the official Rust SDK. Two revisions are current and both are served: 2025-11-25, with an initialize handshake, and 2026-07-28, which has no handshake — each request names its revision in _meta and server/discover describes the server. Older revisions back to 2024-11-05 are accepted from a client that asks for them.

Every tool is annotated read-only, idempotent and closed-world, so a client can call it without asking.

The two kinds of failure are kept apart, because MCP distinguishes them and a model only ever sees one of them.

A tool that ran and could not do the job — a malformed document, an invalid expression — is a *successful* JSON-RPC response carrying isError: true. The model sees the text and can correct itself.

A request the protocol rejects — malformed JSON, an unknown method, a request with an id but no method — is a JSON-RPC error with the standard code, or an HTTP status over HTTP. Nothing ran, and the client handles it rather than the model.

Errors

A malformed document is not a crash and not a protocol error:

{"name":"xml_check","arguments":{"xml":"<a>"}}

{"content":[{"text":"…not well-formed…","type":"text"}],"isError":true}

The model reads that text and can fix the document or tell the user.

Design

Five tools, not fourteen. Every tool description is in the model's context on every request. A server with twenty narrow tools spends more contex