MCP servers · Semantix

MCP is a standard way to give a model tools it doesn't ship with: your issue tracker, your database, a browser, your own scripts. Add a server here and everything it exposes becomes available to the model in conversation, named mcp__<server>__<tool>.

(The one-shot "Ask" surfaces — asking for a 3D style or a theme — never get MCP tools, whatever you have connected here.)

They run on your machine. Semantix connects to them itself — nothing about your MCP setup is relayed through a remote service. A local stdio server is started as a child process of Semantix, with your permissions, on your computer. A remote one is dialled from your machine directly.

This matters for two practical reasons: a local server can see whatever your user account can see, and a remote one only needs to be reachable from where you're sitting.

Adding one#

Add server, then pick a transport.

Name becomes the namespace. Lowercase letters, digits, _ and -; up to 64 characters. Tools from a server called github arrive as mcp__github__*.

stdio (local command) — a program on your machine. Command is the executable, Arguments are space-separated:

Command    npx
Arguments  -y @modelcontextprotocol/server-everything

There's no quoting in that field, so an argument containing a space can't be expressed here — quotes are passed through as literal characters. Use a wrapper script, or edit the file by hand.

HTTP (streamable) — a remote endpoint. URL, plus an optional auth header:

URL                https://mcp.linear.app/mcp
Auth header name   Authorization
Auth header value  Bearer lin_api_…

Changes take effect straight away. Semantix reconnects as you save — no restart, and no need to start a new conversation.

Note

SSE (legacy) is dialled exactly like HTTP (streamable) in this build. If a server speaks only the older SSE protocol, it won't connect under either option.

Whether it worked#

Each row carries a small dot on the left:

green — connected
red — the connection failed; hover it to read the reason
grey — parked
no dot — health unknown: either not checked yet, or Semantix couldn't reach its own MCP host, in which case every row loses its dot at once

The reason only lives in that tooltip, so hover before assuming anything.

The refresh button at the top re-dials failed servers immediately. Without it, a failed server is only retried when something asks the host — the next message you send, or opening this tab — and never more often than every thirty seconds. Nothing retries in the background while you're idle.

You'll see real messages there: spawn 'npx': No such file or directory (os error 2), initialize timed out after 10s, transport closed.

Note

The first message after adding a server can go out without its tools. Semantix waits five seconds for a server to hand back its catalogue; if it's still starting, the turn is sent without it and nothing tells you. The model simply behaves as though the server isn't there. Send again.

Why a local server usually fails the first time#

If a stdio server shows red with No such file or directory, the command exists — your shell can run it — but Semantix can't find it.

A desktop application doesn't inherit the PATH your terminal has. Anything installed through nvm, asdf, mise, or Homebrew in a non-standard prefix is invisible to it.

Use an absolute path in the Command field:

/home/you/.nvm/versions/node/v22.14.0/bin/npx

which npx in your terminal will tell you what to paste. Same for uvx, python, docker and anything else — Semantix installs none of them, and doesn't check whether they exist before you save.

Turning one off, and removing it#

The On / Off pill parks a server without deleting it — the configuration stays, the connection stops, and the model no longer sees its tools. Useful for a server that's noisy or expensive.

Delete asks once, then removes it. No undo.

Renaming is allowed, and changes the namespace its tools appear under.

Where the configuration lives#

~/.semantix/USER/mcp-servers.json

One file for all your projects, on this machine. It's the standard mcpServers format, so a config from another MCP-aware tool can usually be pasted straight in. Semantix adds one field of its own, "enabled": false, for a parked server.

The Raw toggle at the top shows you that file as it's stored. It's a viewer, not an editor.

Auth headers live in this file in plain text. On Linux and macOS it's created readable only by your own user account; on Windows it gets no special permissions.

Note

The file supports things the form doesn't — environment variables for a stdio server, and more than one auth header. You can add them by hand, and they work.

But editing that server through the form afterwards will silently drop them. The form rebuilds the entry from its own fields. If you've hand-edited an entry, keep editing it by hand.

What the model can do with them#

Two things worth knowing before you connect a server that can change anything.

You can't see a server's tools in the interface. There's no catalogue anywhere in Settings. You find out what a server offers by watching the model use it, or from the server's own documentation.

MCP tools are never covered by the approval prompt. On one of your own custom models, Semantix's file-writing and shell tools ask before they act — MCP tools don't. On the Claude Code lane nothing asks at all, native tools and MCP tools alike.

So a connected server runs what the model asks of it, without a prompt, on every lane.

That's fine for a read-only server. For one that can write files, send messages, or change data in a system you care about, connect it deliberately, and park it when you're not using it.

→ What the agent can do