MCP servers

Model Context Protocol is an open standard for exposing tools, prompts, and data to an AI agent over a small JSON-RPC interface. A server implements it once — a GitHub server, a Postgres server, a docs server — and any MCP-aware client can use it. ORG-2 is such a client: it connects to the servers you configure, merges their tools into the session's registry alongside the built-in ones, and records every call in the same trajectory. This page covers connecting servers, scoping them, feeding them credentials, and fixing them when they will not start.

Transports

ORG-2 supports three transports, and the type field in the config picks one:

The initial handshake must complete within timeout seconds, default 30. Servers connect in the background when a session starts, so a slow server delays its own tools rather than the session.

Adding a server through the UI

1. Open Settings → Skills, MCPs & Plugins and select the MCP tab. The toolbar and Spotlight both offer Add MCP server as a shortcut into the same place.
2. Click Add MCP Server.
3. Fill in Server Name — "Unique identifier for this MCP server". It appears in every tool the server contributes, so keep it short.
4. Pick a Transport: stdio, SSE, or Streamable HTTP.
5. Pick a Scope: User or Repo-specific. The field's help text names the files it writes: ~/.orgii/mcp-servers.json or <repo>/.orgii/mcp-servers.json.
6. For stdio, fill in Command (for example npx), Arguments (shell-quoted, for example -y @modelcontextprotocol/server-filesystem /tmp), an optional Working directory, and any Environment Variables as key/value rows. For SSE or Streamable HTTP, fill in URL and any Headers.
7. Optionally set Auto-approve tools and Connect timeout (seconds), and leave Enabled on.
8. Click Test Connection. On success you get "Connection successful" and a count of tools discovered. Then Save.

Already have servers configured elsewhere? The Import MCP servers from other apps panel below the table scans for mcp.json and mcp-servers.json under .cursor/, .claude/, and .vscode/ in your repos, and under ~/.cursor/ and ~/.claude/ at user level, and offers each for import.

The config file

Both scopes use the same schema, keyed by server name under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"],
      "disabled": false,
      "timeout": 30
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
      "autoApprove": ["search_repositories", "get_file_contents"]
    },
    "docs": {
      "type": "streamableHttp",
      "url": "https://${MCP_HOST:-api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" },
      "disabled": false,
      "timeout": 60
    }
  }
}

Every field except type is optional; disabled defaults to false and timeout to 30. A malformed file is never silently overwritten — ORG-2 refuses to save over JSON it could not parse and reports Failed to parse MCP config <path> instead.

Credentials and environment variables

Do not paste secrets into the config file. String fields support shell-style expansion, so the file can reference variables from the environment ORG-2 runs in:

• ${VAR} — expands, and errors if the variable is unset or empty.
• ${VAR:-default} — falls back to default when the variable is unset or empty.
• $HOME without braces stays literal, and unmatched patterns pass through untouched.

Expansion applies to command, each element of args, the values in env, url, and the values in headers. It deliberately does not apply to cwd, so directory names never become a place to hide secrets.

For remote servers that speak OAuth, ORG-2 runs the flow itself rather than asking you for a token. When a server reports that it needs authentication its status becomes Auth needed, and the only tool it contributes is mcp__<server>__authenticate. Calling that tool binds a local callback, opens your browser, registers ORG-2 with the identity provider as ORGII MCP Client, waits up to ten minutes, stores the credentials locally, and reconnects the server so its real tools appear. The needs-auth state is cached for 15 minutes so an unauthenticated server is not hammered on every session. stdio servers cannot use this flow — authenticate them with env instead.

User scope versus repo scope

User servers live in ~/.orgii/mcp-servers.json and load in every workspace. Repo-specific servers live in <repo>/.orgii/mcp-servers.json and load only for sessions in that repo, which suits a project-specific database or issue tracker.

When the same name exists in both files, the repo entry wins for connection details — command, URL, environment, headers. disabled is the exception: it is the logical OR of both files, so a server switched off at user level stays off even if a repo config re-declares it. The table's scope filter (All / User / Repo-specific) reflects the same split.

Note: repo-scoped entries are read when a session starts in that repo. If the Repo-specific tab looks empty from the settings screen, edit <repo>/.orgii/mcp-servers.json directly — same schema, effective on the next session.

There is no per-session server picker. A session inherits the merged config plus whatever its agent has disabled.

Choosing which tools an agent gets

Each server's tools are registered under a fully qualified name, mcp__<server>__<tool> — a double underscore separator, with any character outside letters, digits, hyphen, and underscore rewritten to _. That is the name the model calls, the name the trajectory records, and the identifier used everywhere below. The UI strips the prefix and shows the bare tool name.

Three levels of control:

• The whole server. The Enabled switch on each row in the MCP table, or the bulk Enable all / Disable all actions. Disabling writes disabled: true into whichever file owns the entry and stops the process.
• Per agent, per server or per tool. An agent's configuration lists your servers; expand one to get a switch per tool. These write into the agent definition, and exclusions are inherited — a derived agent can add exclusions but not remove a parent's.
• Workspace resources. The Auto load workspace skills, MCPs, and plugins switch on an agent decides whether repo-scoped servers load at all. User-level servers still load when it is off.

The autoApprove field lists tool names — or * for all of them — that are marked pre-approved when the session starts; the wizard's hint is "Leave empty to confirm each call."

Prompts and resources

Servers can expose more than tools. If a connected server publishes prompts, invoke one from the chat input as /mcp__<server>__<prompt> followed by positional arguments: ORG-2 zips them against the prompt's declared argument names, renders the prompt server-side, and substitutes the result for your message before sending. If a server publishes resources, ORG-2 registers two global tools — list_mcp_resources and read_mcp_resource — that take the server name as a parameter, rather than a pair per server.

How MCP calls appear in the trajectory

An MCP call is recorded exactly like a built-in one: the fully qualified mcp__server__tool name, the complete arguments, and the complete result, all searchable later. In the chat panel it renders as a tool block with the MCP icon and the bare tool name.

Servers that report progress get a live row inside that block — a percentage and an n / total count when the total is known, a pulsing indicator and a raw count when it is not — which clears when the result arrives. Failures surface as an MCP server error block. MCP tool definitions are also accounted for separately under an MCP category in the context-usage breakdown, worth checking when many servers are connected.

Troubleshooting a server that will not start

Every server shows one of six statuses:

Work through it in this order:

1. Wait. On first launch a stdio server often has to download its package. The table says "Starting N MCP server(s)… (can take a few seconds)" and, after ten seconds, "Still connecting…".
2. Restart it. Restart on the row's ⋯ menu, or Reconnect in the detail panel, re-runs the handshake without touching the config.
3. Read the error. Open the server and look at the status section: Failed to connect to MCP server '<name>' carries the underlying cause verbatim.
4. Test the config. Reopen the server in the wizard and click Test Connection, which connects with the edited values without saving them. For stdio, also run the exact command and args in a terminal — most failures are a missing binary, a wrong path, or an uninstalled package.
5. Check variables and timeout. If the error names an undefined environment variable, export it where ORG-2 can see it or switch to ${VAR:-default}. If the server is simply slow to boot, raise Connect timeout (seconds).
6. Validate the JSON. Failed to parse MCP config <path> means the file is malformed. Fix it in an editor — ORG-2 will not overwrite it while it is broken.

Repeated transport-level failures during a session are handled automatically: after three terminal errors on a connection, ORG-2 drops it and reconnects. A tool that merely returns an error does not count, because the connection is still healthy.

Next steps

• Tools — the built-in tool surface MCP servers extend.
• Agents — per-agent tool policy, including which MCP servers an agent may use.
• Skills — the other way to extend an agent, with procedures instead of tools.
• Security — approval prompts and where credentials are stored.