Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jundot/omlx/llms.txt

Use this file to discover all available pages before exploring further.

The Model Context Protocol (MCP) is an open standard that lets LLMs call external tools — reading files, querying databases, running web searches, and more — without custom application glue code. oMLX integrates MCP at the server level, so any client connected to your oMLX endpoint automatically has access to the tools you configure. Tool calls are resolved server-side and the results are injected into the conversation before the next generation step.

​
Installing MCP support

MCP support is an optional dependency. Install it using the method that matches how you installed oMLX. 
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

​
Starting the server with MCP

Pass your MCP config file to omlx serve via --mcp-config: 
omlx serve --model-dir ~/models --mcp-config mcp.json
You can also set the config path through an environment variable instead of a CLI flag: 
export OMLX_MCP_CONFIG=/path/to/mcp.json
omlx serve --model-dir ~/models
The config path is resolved in this order: CLI flag → OMLX_MCP_CONFIG env var → ./mcp.json → ~/.config/omlx/mcp.json.

​
Config file format

Create a mcp.json file to define which MCP servers to connect. The example below mirrors the mcp.example.json shipped with oMLX: 
{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true,
      "timeout": 30
    },
    "sqlite": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "data.db"],
      "enabled": false,
      "timeout": 30
    },
    "web-search": {
      "transport": "sse",
      "url": "http://localhost:3001/sse",
      "enabled": false,
      "timeout": 60
    }
  },
  "max_tool_calls": 10,
  "default_timeout": 30.0
}
Set "enabled": false on any server you want to define but not connect at startup. You can re-enable it later without removing the config entry.

​
Top-level fields

FieldTypeDescription
max_tool_callsintegerMaximum number of tool call rounds per request (default: 10)
default_timeoutfloatDefault per-call timeout in seconds (default: 30.0)

​
Server fields

FieldTypeDescription
transportstringstdio or sse
commandstringExecutable to run (stdio only, e.g. npx, uvx)
argsarrayArguments for the command (stdio only)
urlstringSSE endpoint URL (sse only)
enabledbooleanWhether to connect this server at startup
timeoutintegerPer-server timeout override in seconds

​
Transport types

oMLX spawns the MCP server as a child process and communicates via stdin/stdout. Use this for local tool servers installed via npx or uvx. The command and args fields are required.
oMLX connects to an already-running MCP server via Server-Sent Events over HTTP. Use this for remote or separately managed tool services. The url field is required; command and args are ignored.

​
MCP API endpoints

When MCP is configured, oMLX exposes three additional REST endpoints for inspecting and manually invoking tools:
MethodEndpointDescription
GET/v1/mcp/toolsList all tools from all connected MCP servers
GET/v1/mcp/serversGet connection status of each configured MCP server
POST/v1/mcp/executeExecute a specific MCP tool by name
These endpoints are useful for debugging your MCP setup or building custom tooling on top of oMLX. 
# Check which tools are available
curl http://localhost:8000/v1/mcp/tools

# Check server connection status
curl http://localhost:8000/v1/mcp/servers

# Execute a tool directly
curl -X POST http://localhost:8000/v1/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "filesystem__read_file", "arguments": {"path": "/tmp/test.txt"}}'
If the server was not started with --mcp-config, /v1/mcp/execute returns HTTP 503. The tools and servers endpoints return empty lists rather than an error.

Build docs developers (and LLMs) love

Get started for freeTalk to us