MCP Server Overview¶

jpx can run as an MCP (Model Context Protocol) server, allowing AI assistants like Claude to use JMESPath for JSON querying and transformation.

What is MCP?¶

MCP is an open protocol that enables AI assistants to interact with external tools and data sources. By running jpx as an MCP server, you give Claude (and other MCP-compatible assistants) the ability to:

Query JSON data using JMESPath expressions
Transform and manipulate JSON structures
Use all 470+ extension functions
Explore available functions and their documentation

Why Use jpx with Claude?¶

When working with JSON data in Claude, jpx provides:

Precise queries: Extract exactly the data you need
Complex transformations: Reshape data structures on the fly
Powerful functions: String manipulation, math, dates, hashing, and more
Consistent results: Deterministic query execution

Available Tools¶

The MCP server exposes 34 tools organized by purpose:

Query Execution¶

Tool	Description
`evaluate`	Run a JMESPath expression against JSON text input
`evaluate_json`	Query a native JSON value; return a versioned structured result
`evaluate_file`	Query permitted JSON files directly from disk (disabled by default over HTTP)
`batch_evaluate`	Run multiple expressions against the same input
`batch_evaluate_json`	Query a native JSON value with ordered structured results and per-expression errors
`validate`	Check expression syntax without executing
`explain`	Break down an expression into steps with complexity rating

For programmatic composition, pass a source tool's structured value as the required input to evaluate_json or batch_evaluate_json. Strings stay literal; explicit null is valid. These two tools advertise output schemas and return schema_version: 1 envelopes in both structuredContent and JSON text. Input is limited to 50 MiB of compact serialized UTF-8 JSON, and batches to 1000 expressions. Transport allocation, evaluation allocation and output size are not bounded by these checks. See typed tool contracts and the programmatic example.

Function Discovery¶

Tool	Description
`search`	Fuzzy search for functions by name, description, category, or signature
`similar`	Find functions related to a specified function
`suggest_function`	Describe a task in natural language and get ranked function suggestions
`functions`	List available functions (optionally filter by category)
`describe`	Get detailed info for a specific function
`batch_describe`	Get details for several functions in one call
`categories`	List all function categories

JSON Utilities¶

Tools for JSON manipulation (RFC 6902/7396):

Tool	Description
`format`	Pretty-print JSON with configurable indentation
`diff`	Generate RFC 6902 JSON Patch between documents
`patch`	Apply RFC 6902 JSON Patch operations
`merge`	Apply RFC 7396 JSON Merge Patch
`keys`	Extract object keys (optionally recursive with dot notation)
`stats`	Analyze JSON structure (type, size, depth, field analysis)
`paths`	Extract all paths in dot notation (e.g., `users[0].name`)
`inspect`	Bounded JSON Pointer preview with depth, path, sample and byte limits

Query Store¶

Ephemeral, process-scoped named queries for iterative development:

Tool	Description
`define_query`	Store a named query for reuse
`get_query`	Retrieve a stored query by name
`delete_query`	Delete a stored query
`list_queries`	List all stored queries
`run_query`	Execute a stored query against JSON input

Multi-Server Discovery¶

Tools for semantic search across multiple MCP servers (see Discovery):

Tool	Description
`register_tools`	Register an MCP server's tools for BM25 indexing
`query_tools`	Semantic search across registered tools
`similar_tools`	Find tools related to a specific tool
`unregister_discovery`	Remove a server from the registry
`list_discovery_servers`	List registered servers
`list_discovery_categories`	List tool categories across servers

Server Info¶

Tool	Description
`engine_info`	Get engine version, function count, categories, and optional discovery schema

Typical Workflow for AI Agents¶

Analyze data: Use stats and paths to understand the JSON structure
Discover functions: Use search to find relevant functions, similar to explore alternatives
Build query: Use validate to check syntax, explain to understand complex expressions
Execute: Use evaluate/batch_evaluate for JSON text or evaluate_json/batch_evaluate_json for native JSON values
Iterate: Use define_query and run_query to save and refine queries
Transform: Use diff, patch, or merge for modifications

Getting Started¶

See Setup to configure jpx as an MCP server for Claude Desktop.