ion MCP server
Commit Nov 13, 2026A headless, multi-provider LLM runtime that handles agent loops, tool execution, and conversation persistence for building custom agent systems.
Also known as dsswift/ion
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is ion MCP?
ion is a headless, multi-provider LLM runtime that handles agent loops, tool execution, and conversation persistence for building custom agent systems.
Summary generated from the project's README
About ion MCP server
Building custom agent systems for specialized domains like research pipelines or warehouse operations is possible with this headless LLM runtime. It provides a foundation for developers to create their own interfaces and workflows by managing the complex agent loop, parallel tool execution, and conversation persistence. The engine operates as a single static Go binary that requires no runtime dependencies, making it easy to deploy in containers, CI pipelines, or as a sidecar.
Users can interact with the engine through one-shot commands for scripted automation or by running a daemon for persistent, multi-client sessions. It supports 14 LLM providers including OpenAI, Anthropic, and Ollama, and allows for any-language extensions via JSON-RPC over stdin/stdout. Developers can implement security through OS-level sandboxing, secret redaction, and permission engines. The system also features native support for parallel sub-agents and dual-transport MCP clients for both local and remote resource reading.
What you can do with it
- 1Automating scripted workflowsA developer can use one-shot mode to run self-contained agent tasks within shell scripts, cron jobs, or git hooks.
- 2Building multi-interface applicationsYou can connect a CLI, a desktop app, and a web interface to a single running daemon simultaneously.
- 3Coordinating specialized sub-agentsAn orchestrator can spawn child agents using different models to perform concurrent tasks like research and formatting.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEYGOOGLE_API_KEYOPENAI_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledsswift/ion is public and reachablegithub.com/dsswift/ion ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/dsswift/ion ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubA headless agent runtime. One binary. Zero opinions. Seventy-three hooks to make it yours.
~13 MB static binary · 14 LLM providers · 73 extension hooks · 15 built-in tools · MIT license
Ion Engine is a headless, multi-provider LLM runtime for building agent systems in any domain. It runs as a single static Go binary with no runtime dependencies. Extensions speak JSON-RPC over stdin/stdout in any language. Your job is the interface, the workflow, and the domain. The engine handles the rest.
The Age of Harness Engineering
The AI agent ecosystem is splitting in two. On one side, opinionated apps that decide how you work. On the other, raw APIs that leave you building the agent loop, the tool execution, the sandboxing, and the conversation management from scratch.
Ion Engine sits in between. It handles the hard parts: the agent loop, parallel tool execution, conversation persistence with branching, and multi-provider abstraction. It ships opt-in security primitives (dangerous command patterns, sensitive path protection, secret redaction, OS-level sandboxing) that you enable when you need them. But it has zero opinions about your interface, your workflow, your permission model, or your deployment target.
You get a raw agent and shape what it becomes.
Where Ion Fits
Tools like Claude Code and Pi are excellent at what they do. If you want a polished coding assistant or a batteries-included agent toolkit, use them. They're built for that, they're well-supported, and they have strong communities.
Ion is different in kind, not in quality. It's a foundation: a headless runtime you build on top of, not a product you use as-is. Think of it as the engine block, not the car.
What Ion gives you:
- A domain-agnostic runtime. No coding-tool assumptions. Build agent systems for warehouse ops, research pipelines, farm management, incident response, or your own coding assistant.
- Any-language extensions. Extensions communicate via JSON-RPC over stdin/stdout. Write them in Go, Python, Rust, TypeScript, or a shell script. If your language can read stdin and write stdout, it's an extension language.
- Daemon architecture with multi-client broadcast. Multiple clients connect to the same engine simultaneously. Build a CLI, a desktop app, and a web interface that all share one running daemon.
- Native parallel sub-agents. Spawn child agents with different models that run their own tool loops concurrently. A parent on Opus coordinates researchers on Sonnet and formatters on Haiku.
- Built-in security primitives. OS-level sandboxing (Seatbelt on macOS, bwrap on Linux), secret redaction, dangerous command blocking, and a permission engine with LLM-based classification.
- Enterprise policy enforcement. 4-layer config merge (defaults, user, project, enterprise) where the enterprise layer is sealed. Security sets the floor; developers customize above it.
- Zero vendor SDK dependencies. LLM providers via raw HTTP with manual SSE parsing. No transitive dependency chain you don't control. Fork the binary, keep your agents.
- MCP support. Dual-transport MCP client (stdio for local servers, SSE for remote) with resource reading exposed as first-class tools.
- Credential management. Five-level resolver: programmatic override, environment variables, OS keychain, encrypted file store, and CLI proxy for TOS-compliant subscription access via Claude Code.
- Extension hooks across every stage of the agent loop. Intercept and modify behavior wherever you need to.
You want to build your own coding agent? Use this engine and wrap your own opinions around it. You want non-coding agent orchestrations? Build harnesses that coordinate domain-specific agents. You want to embed an agent runtime in a container sidecar, a CI pipeline, or a web API? It's a single static Go binary with no runtime dependencies.
Ion is a starting point. The runtime handles the hard parts and stays out of the way on everything else.
Quick Start
# Install (macOS)
curl -fsSL https://github.com/dsswift/ion/releases/latest/download/ion-darwin-arm64 \
-o /usr/local/bin/ion && chmod +x /usr/local/bin/ion
Ion ships with no default model. That is a deliberate choice. You bring the opinions, including which model runs your agents. Drop a config at ~/.ion/engine.json before your first prompt:
{
"defaultModel": "qwen2.5:14b",
"providers": {
"ollama": {}
}
}
The example above runs qwen2.5:14b locally on Ollama with no API key required. Other supported models work the same way: gpt-4o for OpenAI, claude-sonnet-4-6 for Anthropic, mistral-large-latest for Mistral. Set defaultModel to whichever model you want and configure its provider block. See the Model and Provider Configuration section below or the Provider Setup docs for the full catalog.
For hosted providers, export the matching credential before running:
export OPENAI_API_KEY="sk-..."
# or ANTHROPIC_API_KEY, GOOGLE_API_KEY, MISTRAL_API_KEY, etc.
Now run your first prompt:
ion prompt "What files are in the current directory?"
One command. The engine starts in-process, calls the LLM, executes tools, streams the result to stdout, and exits. No daemon, no socket, no background process.
One-shot mode works well for scripted workflows: shell scripts, cron jobs, git hooks, CI pipelines, orchestration scripts. Each invocation is self-contained.
# One-shot with JSON output
ion prompt --output json "Summarize the last 5 commits" | jq -r '.result'
# One-shot with streaming NDJSON (for piping to other tools)
ion prompt --output stream-json "Review this diff for security issues"
# Skip configured extensions for this run
ion prompt --no-extensions "What time is it in UTC?"
# Clear configured extensions, load only this one
ion prompt --no-extensions --extension ./my-reviewer/index.js "Review the staged changes"
Daemon mode
When you need persistent sessions, multiple clients, or real-time event streaming, run the engine as a daemon.
# Start the daemon
ion serve
# Ion Engine v1.0.0 started (pid 42871)
# Socket: /Users/you/.ion/engine.sock
# Start a session with a working directory and extensions
ion start --key myproject --dir /path/to/project \
--extension ~/.ion/extensions/my-harness.js
# Send a prompt (routed to the session by key)
ion prompt --key myproject "What files are in the current directory?"
# Prompt sent. Use `ion attach` to stream output.
# Stream events (NDJSON lines flow as the agent works)
ion attach
# {"type":"text_chunk","text":"I can see the following files..."}
# {"type":"tool_call","toolName":"Bash","toolId":"tool_1","index":0}
# {"type":"tool_result","toolId":"tool_1","output":"README.md\nsrc/\ntests/\n"}
# {"type":"text_chunk","text":"The directory contains a README..."}
# {"type":"task_complete","result":"...","costUsd":0.003,"numTurns":1}
# Send a follow-up (the session remembers context)
ion prompt --key myproject "Which of those files changed in the last week?"
# Send another (still the same conversation)
ion prompt --key myproject "Show me the diff for the most recent change"
# Start a second session with different extensions
ion start --key infra --dir /path/to/infra-repo \
--extension ~/.ion/extensions/terraform-tools.js
# Both sessions run in parallel, each with their own extensions
ion prompt --key infra "Plan the changes in modules/networking"
# Check what sessions are running
ion status
# KEY DIRECTORY STATE
# -------------------------------------------------------
# myproject /path/to/project active
# infra /path/to/infra-repo active
# Filter attach to one session
ion attach --key myproject
# Stop a session when done
ion stop --key myproject
# Shut down the daemon
ion shutdown
Why daemon mode:
- Persistent sessions. Conversation history survives across prompts. Ask a follow-up without re-sending context. Branch a conversation to explore alternatives. The engine manages session state, compaction, and JSONL persistence automatically.
- Multiple clients. Any number of clients connect to the same daemon simultaneously. Every client receives broadcast events. One engine serves all your interfaces.
- Warm extensions. Extension subprocesses stay alive between prompts. No spawn/init overhead on each invocation. Custom tools, hooks, and agents are ready instantly.
- Real-time streaming. Connect with
ion attachand watch events flow as the agent works. Pipe NDJSON intojq, a monitoring dashboard, or an approval workflow. Build integrations that react to tool calls, text output, and errors in real time. - Session management. Run multiple sessions in parallel, each with its own model, extensions, and working directory. Route prompts to the right session by key. One daemon, many workstreams.
One-shot mode runs a fresh engine per invocation. Daemon mode runs one engine that serves everything. Use one-shot for scripts and automation. Use daemon mode for applications and interactive workflows. Both load the same config, run the extensions you specify (passed with --extension or listed in ~/.ion/settings.json profiles), and run the same agent loop.
See the engine docs for Linux, Windows, and Docker install instructions.
Documentation
Full technical documentation lives in docs/. Start here based on what you're building:
| Audience | Start with |
|---|---|
| Harness engineer building extensions | Quick Start, Extension Guide, Hooks Reference |
| IT admin deploying Ion | Configuration, Security, Enterprise |
| Contributor working on the engine | Architecture, Contributing |
Key references: Socket Protocol | CLI Reference | Tools Reference | Provider Setup | MCP Integration
Model and Provider Configuration
Ion supports many providers and lets you plug in your own through a common interface. The engine picks a provider in this order: a registered model in ~/.ion/models.json, then a built-in name-prefix match (claude-*, gpt-*, qwen*, llama*, gemini-*, mistral*, grok*, deepseek-*, and so on), then a hard error if neither matches.
Set the model you want in ~/.ion/engine.json and configure its provider block:
{
"defaultModel": "qwen2.5:14b",
"providers": {
"ollama": {},
"openai": { "apiKey": "CUSTOM_OPEN_API_KEY_VAR" },
"anthropic": { "apiKey": "sk-ant-..." }
}
}
How
apiKeyis resolved. TheapiKeyfield accepts three forms:
- Omitted: the engine auto-resolves the key from provider's default environment variables (e.g.
OPENAI_API_KEY), the system keychain, or its encrypted file store.- An environment variable name (all-caps, digits, and underscores, e.g.
"OPENAI_API_KEY"): expanded from the environment at startup.- A literal key (e.g.
"sk-proj-..."): used directly as-is.The examples above use both form 1 and form 2. The value
"CUSTOM_OPEN_API_KEY_VAR"is not a literal API key; it tells the engine to read the corresponding environment variable.
Need a custom name (a finetune, an OpenRouter route, a tier alias)? Register it under ~/.ion/models.json:
{
"tiers": {
"fast": "qwen2.5:7b",
"smart": "claude-sonnet-4-6"
},
"providers": {
"ollama": {
"models": {
"myteam/qwen-finetune:latest": { "contextWindow": 32768 }
}
}
}
}
Need to mix cloud and local models in one workflow? See the Workflows: Model Routing example below.
For the full picture, see the models.json reference, the engine.json reference, and the provider catalog.
One Engine, Many Shapes
Ion Engine is a raw agent. On its own, it takes a prompt, talks to an LLM, executes tools, and streams results back. That's it. No opinions. No workflow. No interface. No system prompt. The engine ships with no guiding instructions. Every behavior is something you bring.
What matters is what you build around it.
A shell script
The simplest harness is a few lines of bash. Send a prompt, get a result. Embed an AI agent in a cron job, a git hook, or a CI pipeline with nothing more than a shell script.
#!/bin/bash
ion prompt --output json "Review the diff and flag any security concerns" \
| jq -r '.result' \
>> review-output.md
A full application
Any socket client can be a full application. Your UI connects to the engine's Unix socket, sends JSON commands, and renders streamed events. The engine runs every session. Your app is purely an interface.
Your App ──[Unix socket]──> Ion Engine
The wiring is a thin socket client. Connect, write JSON lines, parse events:
// Example socket client (simplified)
import { createConnection } from 'net'
import { join } from 'path'
import { homedir } from 'os'
const SOCKET = join(homedir(), '.ion', 'engine.sock')
const conn = createConnection(SOCKET)
// Send commands as NDJSON
conn.write(JSON.stringify({ cmd: 'start_session', key: 's1', config: { model: 'qwen2.5:14b' } }) + '\n')
conn.write(JSON.stringify({ cmd: 'send_prompt', key: 's1', text: 'What files are here?' }) + '\n')
// Receive events as NDJSON. Each line is { key, event }, where key is the
// session that produced it and event.type is an engine_-prefixed variant.
let buffer = ''
conn.on('data', (chunk) => {
buffer += chunk.toString()
let nl
while ((nl = buffer.indexOf('\n')) !== -1) {
const { key, event } = JSON.parse(buffer.slice(0, nl))
buffer = buffer.slice(nl + 1)
// engine_text_chunk, engine_tool_call, engine_tool_result,
// engine_task_complete, ...
}
})
The client never calls an LLM or executes a tool. It sends commands to the engine, and the engine handles the rest.
Notice the key field in every command. That's session routing. Every session gets a unique key, and any client can send prompts or filter events by key. A tabbed desktop app uses keys for tabs. A container singleton launched by a KEDA scaler uses keys to multiplex queue events. A CI pipeline uses keys to run parallel review sessions. One daemon, many independent sessions, any number of clients.
A workflow orchestration
An extension can register multiple agents, each with its own model, tools, and system prompt. A single prompt to a well-built harness can trigger an entire workflow: the LLM delegates to specialized agents, they run their tool loops in parallel, and the results flow back to the parent session.
#!/bin/bash
# Full QA pipeline in two harness invocations
# Step 1: QA harness -- one extension with review, test, and report agents
# The LLM orchestrates internally: reviews the diff, generates tests,
# runs them, and produces a structured report. One prompt, multiple agents.
report=$(ion prompt --output json --extension ./extensions/qa-harness.js \
"Review the staged diff for security and style issues. Generate tests \
for anything flagged. Run the tests. Produce a structured QA report \
with pass/fail status, issue severity, and coverage metrics.")
# Step 2: Publication harness -- different extension, different agents
# This harness has agents for formatting, email drafting, and Slack posting.
# It picks up where the QA harness left off.
echo "$report" | jq -r '.result' | \
ion prompt --extension ./extensions/publish-harness.js \
"Format this QA report for stakeholders. Post a summary to #engineering \
in Slack. Email the full report to the team leads."
The QA harness extension registers a code-reviewer agent, a test-writer agent, and a report-generator agent. It also registers tools: lint, run_tests, coverage. When the LLM receives the prompt, it delegates to each agent as needed. The agents run their own tool loops, call the extension's custom tools, and report back. The harness handles the entire review-test-report workflow internally.
The publication harness is a completely different extension with its own agents (formatter, email-drafter, slack-poster) and tools (send_email, post_slack, render_pdf). It knows nothing about code review. It takes structured input and distributes it.
Two invocations, two harnesses. Each one is a self-contained multi-agent system with its own tools, hooks, and orchestration logic. The shell script sequences them and the engine runs each one.
You could also run a single agent per invocation for simple tasks. But the engine supports sub-agents, parallel tool execution, and extension-registered tools specifically so you can build harnesses that do real work in a single prompt, not just wrap one LLM call.
Because the engine communicates over NDJSON on sockets or stdin/stdout, orchestration is language-agnostic. Write the coordinator in Python, Go, bash, or whatever your infrastructure already speaks.
Workflows: model routing
Pick the right model for each step instead of paying flagship rates for tasks a small local model can finish in a second. The --model flag overrides config per invocation, so a single shell pipeline can mix local and hosted models freely.
#!/bin/bash
# Three-step pipeline that mixes local and hosted models per step.
# Step 1: classify intent on a small local model. Fast, cheap, no API calls.
intent=$(ion prompt --output json --model qwen2.5:14b \
"Classify the topic of this message in one word: '$1'" | jq -r '.result')
# Step 2: deep reasoning on a hosted model that handles structured tasks well.
analysis=$(ion prompt --output json --model gpt-4o \
"The intent is '$intent'. Plan a response that addresses it." | jq -r '.result')
# Step 3: long-form writeup on a long-context model.
ion prompt --model claude-sonnet-4-6 \
"Using this plan, write the final response. Plan: $analysis"
Three models, three providers, one shell script. The engine resolves each model via prefix match (qwen* to Ollama, gpt-* to OpenAI, claude-* to Anthropic), pulls the matching credential from the environment or config, and runs each step in turn. See the models.json reference for tier aliases that let you write --model fast instead of pinning a specific model name.
A web API with an engine sidecar
Run the engine as a sidecar process behind a web server. The API handles auth and routing. The engine handles the agent loop.
# Flask API with Ion Engine sidecar
from flask import Flask, request, jsonify
import subprocess, json
app = Flask(__name__)
@app.route('/chat', methods=['POST'])
def chat():
prompt = request.json['message']
result = subprocess.run(
['ion', 'prompt', '--output', 'json', prompt],
capture_output=True, text=True
)
return jsonify(json.loads(result.stdout))
For streaming, connect to the socket directly and forward NDJSON events over SSE or WebSocket.
Deployment in containers
Package any of the above patterns into a container and run them wherever containers run.
FROM alpine:3.20
COPY ion /usr/local/bin/ion
COPY orchestrate.sh /app/orchestrate.sh
COPY extensions/ /app/extensions/
ENTRYPOINT ["/app/orchestrate.sh"]
# Single agent container, pointed at a local Ollama daemon on the host
docker run --network host ion-engine prompt "Analyze this codebase"
# Orchestration script inside a container, using whichever provider you set up
docker run -e $YOUR_PROVIDER_API_KEY ion-orchestrator
# Multiple specialized containers
docker compose up reviewer test-writer deployer
Sub-Agents
A session can spawn child agents that run their own tool loops in parallel, report back, and disappear. Two ways to define them, but in both cases: the harness decides which agents load. The engine provides the discovery API and the spawning infrastructure. It never auto-loads agents on its own.
Inline agents (via extensions)
Register agents in your extension's init response. They live in code, ship with the extension, and work anywhere the extension loads.
// Inside your extension's init handler
reply(msg.id, {
name: 'db-explorer',
agents: [
{ name: 'analyst', description: 'Write and run SQL queries to answer data questions', model: 'gpt-4o' },
{ name: 'summarizer', description: 'Summarize query results into plain language', model: 'qwen2.5:14b' }
]
})
Good for agents tightly coupled to extension logic. But when agents need long system prompts, specialized tool sets, or per-project customization, files on disk are better.
Agents from disk
Agent definitions are markdown files with YAML frontmatter. The engine provides a discovery API (agentdiscovery.Discover()) that walks directories, parses these files, and builds a dependency graph. But discovery is a library call, not an automatic behavior. An extension or harness must call it, decide which agents to accept, and register them with the session.
# ~/.ion/agents/code-reviewer.md
---
name: code-reviewer
description: Review code changes for correctness, style, and security
model: qwen2.5:14b
tools: [Read, Grep, Glob, Bash]
---
You are a senior code reviewer. Focus on:
- Logic errors and edge cases
- Security vulnerabilities (injection, auth bypass, data exposure)
- Style consistency with the surrounding codebase
- Performance: flag O(n²) or worse when linear alternatives exist
Read the diff, read the surrounding code for context, then deliver
a structured review. Be direct. Skip praise for things that are simply correct.
The frontmatter declares capabilities and the body becomes the system prompt. Once a harness loads and registers this agent, the LLM can delegate to it by name. It runs its own tool loop with only the tools listed.
Supported fields:
| Field | Purpose |
|---|---|
name |
Agent identifier (defaults to filename if omitted) |
description |
What the LLM sees when deciding whether to delegate |
model |
LLM model override (smaller model = faster + cheaper) |
tools |
Which tools this agent can use |
parent |
Parent agent name for building hierarchies |
Any extra fields land in a Meta map your harness can read for custom routing, tagging, or policy decisions.
ion MCP questions
What is Ion Engine?
Ion Engine is a headless, multi-provider LLM runtime designed as a foundation for building domain-agnostic agent systems.
Does it support MCP?
Yes, it includes dual-transport MCP client support for both local stdio servers and remote SSE.