MCP Servers

An MCP server is a small program that offers the assistant extra tools — reading a ticket system, querying a database, driving a design tool. Pia can start MCP servers that live on your own computer and hand their tools to the assistant alongside its own. Open the list from Settings → Assistant → MCP servers.

MCP servers you add here run on this computer only. Pia starts each one as a local program and talks to it over that program’s input and output. A server that lives on the internet behind a URL cannot be added — Pia turns it down with “Remote servers are not supported — only servers Pia starts on this computer.” Tools delivered by the Pia server are a separate thing, managed under Plugins.

Adding a server

Add server opens a form with five fields:

Field	What goes in it
Name	What you want to call the server. It also decides the tool prefix.
Command	The program Pia runs to start the server — npx, uvx, python, or a full path to an executable.
Arguments	One per line.
Environment variables	One KEY=value per line.
Working directory	Optional. The folder the server starts in.

Environment values are stored encrypted for your Windows account, so an API token you put in one is not readable by another account on the same machine and is never synced to Pia Cloud.

Filling the form in from JSON

Most MCP servers are documented as a JSON snippet for some other client. Rather than transcribing it field by field, paste it into Paste a configuration and press Fill in from JSON. Pia accepts an mcpServers entry, or a bare object with a command in it, and reads the name, command, arguments and environment variables out of it:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Work"]
    }
  }
}

Paste one server at a time. A snippet holding several is turned down with “That holds more than one server. Add them one at a time.” The form stays editable after the JSON is read, so you can correct a path or add a token before saving.

Testing the connection before you save

Test connection starts the server there and then, asks it what tools it offers, and reports back. It is the fastest way to find a wrong path or a missing token, because the alternative is discovering it the first time the assistant reaches for a tool.

• Success reads “Connected. N tool(s) available.” and fills in the tool list below.
• Failure reads “Could not connect: …” with the reason the server gave.

Test connection can take up to 90 seconds the first time. A command like npx -y <package> downloads the server before it answers, and that download happens on the first run only.

Choosing which tools a server may offer

Under Available tools, tick the tools you want the assistant to have. “Only ticked tools are offered to the assistant.” means exactly that: a tool you untick is not merely un-approved, the assistant never learns it exists and cannot ask to run it. All and None set the whole list at once, and a tool that can delete something is marked may delete.

A server you have not tested yet offers all of its tools. The list reads “Test the connection to list this server’s tools” until Pia has seen them, and until you narrow it the server’s whole set is on offer.

Note

Ticking a tool here is not the same as approving it. The tick decides what the assistant can see; whether a tool runs without asking you is a separate question, answered under Tool Permissions.

Tool names are prefixed with the server

Every tool from a local MCP server is renamed <prefix>__<tool> before the assistant sees it — a search tool on a server named “Jira Cloud” becomes jira_cloud__search. The prefix comes from the server’s name, lower-cased with anything that is not a letter or digit turned into an underscore, and it is shown as Tool prefix on the form so you can see what the assistant will call.

Prefixing means two servers that both offer a search tool can be switched on at once without clashing, and neither can shadow one of Pia’s own tools.

Reading a server’s detail page

Selecting a server in the list opens its detail page on the right, which shows:

• Whether it is Running, Disabled, Starting…, or Not running — a server that failed to start says why on the same line.
• Its command, arguments and working directory.
• The names of its environment variables, never their values.
• Every tool it offers, with the ones you withheld marked withheld, and a summary reading “N of M tool(s) offered”.

Test connection sits beside Edit and Delete on that page, so a server that is switched off can still be asked what it offers without turning it on first.

A server that is not running shows the tools it was allowed when it last ran, labelled as such. A server Pia has never started shows “Start this server, or use Test connection, to list its tools.”

Switching a server off, and removing it

Each row in the list has a switch. Turning a server off stops it and withdraws its tools from the assistant; turning it back on starts it again. Editing a server that is running saves and restarts it, which the form reports as “Saving… restarting the server.”

Delete removes the server for good and asks first — “Remove “X”? Its tools stop being available to the assistant.“

When a server will not start

The reason Pia reports comes from the server itself, and these are the common ones:

• The command is not on your PATH. Give the full path to the executable instead of its bare name.
• A required environment variable is missing. Most servers that reach a paid service need an API token in Environment variables.
• The working directory does not exist. Leave it blank unless the server’s own documentation asks for one.
• The first run is still downloading. An npx -y command fetches the package before it answers; test again once it has.

Next Steps

To decide which of these tools may run without asking you each time, see Tool Permissions. For the tools your Pia server delivers, see Plugins.