Skip to main content

Configuration

Neusis Neuron runs as a local (stdio) MCP server that Neusis Code launches for you. Configuration is two steps: create a read-only GitHub token, then register the server in your Neusis Code config.

1. Create a GitHub token​

The server authenticates to GitHub with a Personal Access Token supplied through the GITHUB_PERSONAL_ACCESS_TOKEN environment variable. A read-only fine-grained PAT is all it needs:

  1. Go to github.com/settings/personal-access-tokens/new.
  2. Choose Fine-grained, then Repository access → Only select repositories and pick your KB repo.
  3. Under Repository permissions, set Contents → Read-only. (Metadata → Read-only is selected automatically.)
  4. Generate the token and copy it.

Because the server exposes no write tools, the token never needs write access.

2. Register the server in Neusis Code​

Add the server under the mcp key in neusiscode.json (or .neusiscode/neusiscode.jsonc):

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

Replace OWNER/REPO with your KB repository.

Key points​

  • --kb-repo OWNER/REPO is required. It binds the single repository the server may read. Every tool call operates on this repo only; the agent cannot retarget it.
  • The mcp key name sets the tool-name prefix the agent sees. With the key neusis-neuron, the tools surface as neusis-neuron_get_file_contents, neusis-neuron_get_repository_tree, and neusis-neuron_search_code.
  • Keep your token out of source control. If your Neusis Code config supports environment interpolation, reference an existing variable (for example "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}") instead of pasting the literal token.

:::note stdio only Neusis Neuron supports the stdio transport only. There is no HTTP/remote mode — the server returns an explicit "unsupported transport" error if you try to start one. Always register it as a "type": "local" server. :::

Permission prompts​

Every tool call still goes through Neusis Code's normal permission prompt — the server does not bypass it. You stay in control of what the agent reads. See Permissions.

Troubleshooting​

SymptomFix
--kb-repo is requiredThe --kb-repo OWNER/REPO argument is missing from command. Add it.
Startup fails with an access errorThe token is missing, expired, or lacks Contents: Read on the bound repo. Regenerate it with the correct repository selected.
404 / not found on a fileThe path does not exist in the bound repo (common on a freshly seeded KB). This is returned as a normal result, not a crash — check the path with get_repository_tree.
Tools don't appear in the agentConfirm "enabled": true and that neusis-neuron-mcp is on your PATH (see Installation).