EONYX and MCP: connecting external tools

published on 30.06.2026768 words4 minutes

How to connect MCP servers to EONYX: stdio and HTTP transports, configuration in eonyx.json, tool naming, resources and prompts, toggling servers on the fly, and security.

Contents

Model Context Protocol (MCP) is an open standard.
Through it an agent reaches external systems: databases, APIs, trackers, anything.
EONYX ships an MCP client built on the official Go SDK, modelcontextprotocol/go-sdk.
Servers are described in eonyx.json, and their tools appear to the model next to the built-in ones.

1 🔌 Setup

1.1 Configuration

MCP servers live in the mcp array.
There is no “type” field.
The transport follows from the fields: a url means HTTP, a command means stdio.

A local process, talking over stdin and stdout:

"mcp": [
  {
    "name": "github",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "ghp_..." }
  }
]

env is layered on top of the current environment for the spawned process.

A remote server over HTTP/SSE:

"mcp": [
  {
    "name": "tracker",
    "url": "https://mcp.example.com/sse",
    "headers": { "Authorization": "Bearer $TRACKER_TOKEN" }
  }
]

headers go with every request.
Values may reference environment variables such as $TRACKER_TOKEN, so the token stays out of the file.

Server fields:

Field	Purpose
`name`	server name — becomes the prefix of all its tools
`command`	executable of the stdio server
`args`	command arguments
`env`	environment variables for the server process
`url`	endpoint of the HTTP server (presence of url switches transport)
`headers`	headers for every HTTP request, support `$ENV`

Connection is best-effort

EONYX dials every server at startup.
A failing server is skipped, not fatal.
A warning: mcp: … goes to stderr and the launch continues.
The client introduces itself to the server as eonyx, with the build version.

1.2 Permissions

MCP tools are not always-allowed.
The first call raises an Allow once / Allow always / Deny dialog, like any writing tool.
To stop a trusted tool from asking every time:

"permissions": {
  "allowed_tools": ["github_search_issues", "tracker_get_task"]
}

Security

Keep tokens out of the config text, because the project config is committed.
HTTP headers expand $ENV references for you.
A stdio server’s env values are literal, but the process inherits your environment — so keep the secret in a variable instead.

Add specific tools to allowed_tools, never the whole set.
An MCP server acts on your behalf.

Remember that tool descriptions and results land in the model’s context.
Do not connect a server you do not trust.

1.3 When MCP is not needed

One common case needs no MCP at all.
EONYX has built-in read-only reporting tools for PostgreSQL.
Just set the connection string:

"report": { "database_url": "$DATABASE_URL" }

Leave it empty and the tools are never registered.
That is the off switch.

2 🧠 What the model gets

2.1 Tools

Every tool is registered as <server>_<tool>.
On the github server, search_issues becomes github_search_issues.
The argument schema comes from the server untouched.
The result reaches the model as text.

The path of a single call

sequenceDiagram
    participant M as Model
    participant P as EONYX
    participant S as MCP server
    participant E as External system
    M->>P: github_search_issues call
    P->>S: request over stdio / HTTP
    S->>E: call to the API or database
    E-->>S: data
    S-->>P: result
    P-->>M: result as text

Connecting servers at startup

sequenceDiagram
    participant P as EONYX
    participant A as github server
    participant B as tracker server
    P->>A: connect at startup
    A-->>P: tools registered
    P->>B: connect at startup
    B--xP: server unavailable
    Note over P,B: warning: mcp — skipped
    Note over P: startup continues without it

Working servers register their tools.
A failing one is cut off with a warning.
EONYX starts either way.

2.2 Resources and prompts

EONYX probes the server’s capabilities during registration.
If they are declared, these tools appear too:

Tool	Purpose
`<server>_list_resources`	list the server’s resources
`<server>_read_resource`	read a resource by `uri`
`<server>_list_prompts`	list the prompts
`<server>_get_prompt`	get a prompt by `name` (+ `arguments`)

Binary resources never flood the context.
Instead of the content the model sees the marker (binary resource <uri>, N bytes).

2.3 Managing servers on the fly

Active servers show up in the TUI header, in the » mcp segment.
Ctrl+K opens the capabilities dialog with Skills and MCP tabs.
Any server can be switched off and on inside the session.
Its tools then disappear from the model and stop being called.
No restart, no config edit.
The ✓ and ✗ marks show the state.

3 📋 Summary

Cheat sheet

Configuration
- the mcp array in eonyx.json
- command+args+env for stdio, url+headers for HTTP
Naming
- <server>_<tool> for every tool
- plus resource and prompt tools if the server supports them
Fault tolerance
- a failing server is skipped with a warning
- EONYX always starts
Management
- Ctrl+K turns servers on and off on the fly
- the header shows the active ones
Permissions
- MCP tools go through the common gate
- add trusted ones to allowed_tools by name