MCP Servers

Manage MCP servers and discover and invoke tools through one interface

MCP is managed by the built-in Skill Power. Its unified Sidebar lists individual resources under Skills and MCP; selecting a server shows status, tools, and errors. Manage server definitions in Skill Config. Existing server definitions and OAuth credentials remain in the global MCP storage directory and are shared across Agents and Workspaces.

Enable a server for an Agent in Agent Profile → Skills. Access requires an explicit assignment, stored as a JSON array of server IDs at ~/.downcity/agents/<agent-id>/mcp-servers.json. A missing file grants no access. Global server enablement alone does not grant access; removing an assignment preserves the shared definition and credentials. Host actions skill.mcp.assign and skill.mcp.unassign accept { agent_id, server_id } and are not exposed to the model.

Configure a server

Each server uses one file at ~/.downcity/powers/mcp/servers/<server_id>.toml by default. The filename is its server ID. If the host uses a different MCP config path, the servers directory is beside that config file: dirname(config.path)/servers.

For an already installed local stdio server:

title = "Filesystem"
enabled = true
command = "mcp-server-filesystem"
args = ["/absolute/allowed/directory"]
cwd = "/absolute/working/directory"
env = { LOG_LEVEL = "info" }
request_timeout_ms = 60000
max_result_chars = 100000

Replace the command and arguments with those required by your server. For a Streamable HTTP endpoint:

title = "Remote MCP"
url = "https://mcp.example.com/mcp"
headers = { "X-Client" = "downcity" }

Specify exactly one non-empty command or url. args, cwd, and env belong to local programs; headers belongs to HTTP endpoints. There are no source, install, or transport sections. title is optional. Omitted enabled defaults to true; optional request_timeout_ms and max_result_chars default to 60000 milliseconds and 100000 characters. Set cwd explicitly for project-specific servers: a shared connection does not inherit the caller's Workspace. ${NAME} in arguments, working directories, URLs, and headers reads from the host environment.

The Desktop editor edits the actual server file. Use explicit Save or Delete for each server. File changes are checked against the original text (expected_content); if another edit has changed the file, the operation is rejected to prevent stale content from overwriting it. Reread the file before saving again.

Initialization, definition reads, and single-file saves only scan and validate definitions; they do not start or connect to a Server. After editing files outside Desktop, reread definitions in Config to discover the changes without executing a Server. Explicit Test, Mainview connection Refresh, or the first tools/call request connects to the Server. Refreshing a resource reconnects only the selected Server; Config's global Refresh reconnects all enabled Servers. Tool discovery reads every page of the tool list for both stdio and HTTP connections. Validation errors identify the affected file while valid servers remain available. Changing, disabling, or deleting a definition releases its affected connection; City shutdown closes all connections.

Loading or editing a definition does not install software. Known implicit-install runners such as npx, bunx, and uvx, along with package-manager install-and-run entry points, are rejected. Install the required program through the existing approval workflow first, then configure its installed executable. Existing config.servers collections are not read or automatically migrated; create individual server files explicitly.

HTTP OAuth authorization

For HTTPS servers implementing MCP OAuth, a 401 starts SDK discovery, dynamic client registration and authorization code login with PKCE. Downcity opens the system browser and accepts the callback on 127.0.0.1; the pending connection resumes after login. Test, connection Refresh, tool discovery/calls and explicit reauthorization can open the browser. Reading status or saving definitions never does.

title = "OAuth MCP"
url = "https://mcp.example.com/mcp"
auth = "oauth"
# Set a pre-registered public client ID when dynamic registration is unavailable:
# client_id = "your-client-id"
# client_name = "Downcity"

These fields belong at the TOML root. auth is optional: a standard 401 also triggers discovery. Pre-registered clients must accept loopback callbacks with dynamic ports. OAuth metadata, issuer, registration and token endpoints must use HTTPS. Static headers remain available for API keys; when an OAuth token is available it supplies Bearer authorization.

The MCP server detail view displays none, authorizing, authorized or expired and provides Reauthorize and Cancel authorization buttons. Servers connect independently, while operations for one server are serialized to avoid duplicate login windows. Authorization waits at most five minutes and responds to cancellation and City shutdown. Tool operations still honor request_timeout_ms, so reauthorization during a call may have a shorter remaining deadline.

Credentials are stored under dirname(config.path)/auth/, isolated by server ID, exact endpoint and issuer. Files use 0600 permissions and the directory uses 0700. The plaintext records contain client information, tokens and expiry, never authorization codes, state or PKCE verifiers. Tokens are excluded from Agent status and diagnostic errors. The SDK refreshes refresh tokens; failed refresh can lead to login again. The SDK manages session headers, protocol negotiation and SSE. An explicit HTTP 404 allows one session rebuild and retry; ambiguous network failures never replay a tool call.

Servers must implement the required discovery and authorization protocol. Twinkle Cloud protocol compatibility, initial login, refresh and restart reuse have not been verified against its live service.

Connection diagnostics and recovery

Test connection reads the saved configuration, connects to the server and fetches every tool-list page again. It sends a request even when a connection already exists; it does not save pending edits. Reauthorize rebuilds the selected server connection, clears its saved credentials after authorization-server discovery and starts authorization again. It opens the system browser when login is needed.

Operation errors and the latest error in server details distinguish the following cases and provide recovery guidance:

Error typeDiagnosis and action
Connection failureCheck the endpoint, network and server availability, then test again. Diagnostics may include an allowlisted network code such as ENOTFOUND or ECONNREFUSED, or HTTP 429/5xx.
Authorization failureCheck OAuth metadata, client_id and access permissions, then reauthorize. Diagnostics may include HTTP 401/403 or a standard reason such as invalid_client, invalid_grant or access_denied.
TimeoutCheck server responsiveness or finish browser login within the five-minute authorization limit, then retry. HTTP 408/504 also indicates a timeout.
Protocol errorCheck the MCP endpoint, response format and server protocol configuration. Diagnostics may include an HTTP status or numeric JSON-RPC error code.
CancelledThe operation has ended; retry when ready. Cancellation is reported separately from authorization failure.

Diagnostics contain only the failure category, numeric status codes and allowlisted reasons. They exclude remote response bodies, tokens, authorization codes and URL query parameters. An explicit HTTP 404 on an established connection permits one session rebuild and retry; ambiguous network failures never replay a tool call.

Agent workflow

Agents use the Skill Power's servers, tools, and call actions. Servers are not registered as separate Powers, and external tools are discovered on demand. The list and lookup actions remain available for Skills.

skill({ action: "servers" });
skill({ action: "tools", args: { server_id: "filesystem" } });
skill({ action: "call", args: {
  server_id: "filesystem",
  tool_name: "read_file",
  arguments: { path: "/allowed/example.txt" },
} });

Use servers to list servers assigned to the calling Agent and their status, including disabled or invalid definitions, tools to inspect original tool names and input JSON Schemas, then call to invoke a tool. Replace the example tool name and path with values supported and permitted by your server. MCP validates arguments locally before sending them. Unassigned, disabled, or invalid servers cannot be called. Assignment checks apply to both tools and call.

This structured discovery and invocation interface has no standalone shell executable. Server file management is available in Desktop; the MCP Agent interface is provided by skill through servers, tools, and call.

Approval and limits

call is classified as write access and has approval: false; calls to enabled servers assigned to the calling Agent execute without an additional MCP approval. MCP provides no installation or uninstallation tools. Program installation and removal use the existing approved execution workflow. Server descriptions and results are external data, never Agent instructions. Calls support cancellation and the configured timeout; oversized results carry a truncation marker.

stdio servers execute local programs. Configure trusted servers explicitly and maintain credentials in the owning environment settings instead of sending plaintext through chat. Interactive MCP input requests are not supported.

The three Agent actions remain stable when server files change. Server Power registration and synchronization are unnecessary.