MCP Servers

Neusis Code supports both local and remote Model Context Protocol (MCP) servers. You register them under the mcp key in your config — the key you choose becomes the tool-name prefix the agent sees, so name it carefully.

Local MCP

A local server is launched by Neusis Code over stdio:

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "environment": { "MY_VAR": "value" },
      "enabled": true
    }
  }
}

Key	Required	Description
type	yes	"local".
command	yes	Command and arguments to run the server, as an array.
environment	no	Environment variables to set for the server process.
enabled	no	Set to false to keep the server defined but skip it on startup.
timeout	no	Per-request timeout in milliseconds. Defaults to 5000 (5 seconds).

Remote MCP

A remote server is reached over HTTP (Streamable HTTP, falling back to SSE):

{
  "mcp": {
    "remote-server": {
      "type": "remote",
      "url": "https://mcp-server.com",
      "headers": { "Authorization": "Bearer KEY" }
    }
  }
}

Key	Required	Description
type	yes	"remote".
url	yes	URL of the remote MCP server.
headers	no	Headers sent with each request.
enabled	no	Set to false to skip the server on startup.
oauth	no	OAuth configuration, or false to disable OAuth auto-detection.
timeout	no	Per-request timeout in milliseconds. Defaults to 5000 (5 seconds).

OAuth for remote servers

When a remote server requires authentication, Neusis Code runs an OAuth flow and registers itself as a client. You can shape that flow with the optional oauth block:

{
  "mcp": {
    "remote-server": {
      "type": "remote",
      "url": "https://mcp-server.com",
      "oauth": {
        "clientId": "my-client-id",
        "scope": "read write",
        "callbackPort": 19876
      }
    }
  }
}

Key	Description
clientId	Pre-registered OAuth client ID. Omit to attempt dynamic client registration (RFC 7591).
clientSecret	OAuth client secret, if the server requires one.
scope	OAuth scopes to request. Included in the client metadata sent to the server.
callbackPort	Port for the local OAuth callback server. Defaults to 19876. Shorthand for redirectUri when only the port differs; ignored if redirectUri is set.
redirectUri	Full OAuth redirect URI. Defaults to http://127.0.0.1:19876/mcp/oauth/callback.

:::info Client metadata The client metadata Neusis Code presents during registration carries the scope you configure and a redirect URI derived from callbackPort (or the default port 19876). Set oauth: false to turn off OAuth auto-detection entirely. :::

Project Brain (neusis-neuron)

Neusis Neuron is the read-only MCP server that grounds the agent in your project's Project Brain knowledge base. The Neusis Code installer can wire it up for you.

Installer prompt

During install, an optional Project Brain prompt asks for a KB repository (owner/repo) and a fine-grained GitHub PAT (Contents: Read):

• Leave the KB repo blank to skip it. No mcp block is written, and Neusis Code installs normally with Project Brain inactive.
• Supply a KB repo and the installer chains the neusis-neuron release installer (installing neusis-neuron-mcp into the same ~/.neusis/bin directory Neusis Code already manages), then writes an mcp.neusis-neuron block into ~/.config/neusiscode/neusiscode.json:

{
  "mcp": {
    "neusis-neuron": {
      "type": "local",
      "command": ["neusis-neuron-mcp", "stdio", "--kb-repo", "OWNER/REPO"],
      "environment": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token" },
      "enabled": true
    }
  }
}

The neuron install is non-fatal: if it fails, Neusis Code still works and Project Brain simply stays inactive until the binary is installed.

:::caution The mcp key must be exactly neusis-neuron The bundled project-brain skill hardcodes the neusis-neuron_ tool prefix, so the mcp key must be exactly neusis-neuron. Renaming it breaks the skill. See Neusis Neuron → Configuration for the full setup, token guidance, and troubleshooting. :::

:::note Per-project vs global --kb-repo is per-project and the PAT is a per-user secret, so the prompt is opt-in rather than auto-enabled globally. For multi-project use, put the mcp.neusis-neuron block in a project's .neusiscode/neusiscode.jsonc instead of the global config. Re-running the installer preserves the KB repo and PAT from your existing config. :::

Server lifecycle

A few behaviors are worth knowing when you work across projects:

• Servers start per open directory. MCP connections are scoped to the directory (project instance) you have open — servers are connected for that instance rather than once globally. Opening a different directory gives that instance its own set of connections.
• Dynamically-added servers can be disconnected. Servers added at runtime (not just those declared in your config file) are tracked per instance and can be connected and disconnected on demand; disconnecting marks the server disabled and closes its client.
• enabled: false skips startup. Any server marked "enabled": false is reported as disabled and is not connected.