How to Add a New MCP Server to an Existing OpenWork Setup: UI and Config Methods

You can add a new MCP server to OpenWork either through the Settings → Extensions → MCP UI workflow or by declaring the server in your workspace opencode.json file and restarting the application.

Adding an MCP (Machine-Client Protocol) server extends OpenWork's agent capabilities by exposing external tools and APIs. According to the different-ai/openwork source code, you can register servers either graphically through the desktop application or declaratively via configuration files located in your workspace root or global .opencode directory.

Adding an MCP Server via the OpenWork Desktop UI

When you prefer a graphical approach, OpenWork's desktop interface provides a guided workflow for registering remote MCP endpoints.

Prerequisites

Before registering a server, ensure the OpenWork desktop application is running. The MCP client initializes automatically on startup, exposing a local stdio bridge that handles capability discovery and execution. As documented in [docs/mcp-ui-control-profile.md](https://github.com/different-ai/openwork/blob/dev/docs/mcp-ui-control-profile.md), the desktop app must remain active to maintain the connection.

Step-by-Step UI Configuration

1. Navigate to Settings → Extensions and enable Show hidden to reveal the MCP section.
2. Click Add MCP Server. Alternatively, use HandsFree auto-discover if your MCP client resides on the same machine as the OpenWork app; this automatically populates the connection URL for the built-in OpenWork MCP bridge.
3. Enter the server URL (for example, https://api.example.com/mcp/agent or a custom endpoint).
4. Click Save. The server immediately appears in the MCP server list and becomes available to agents via the search_capabilities and execute_capability tools.

OAuth Authentication Flow

If the remote MCP server requires authentication, OpenWork initiates an OAuth 2.0 flow automatically. The UI launches a browser window to complete registration and securely stores the resulting token. This process is detailed in [docs/external-mcp-oauth.md](https://github.com/different-ai/openwork/blob/dev/docs/external-mcp-oauth.md). Once authenticated, subsequent API calls proceed without additional user interaction.

Registering an MCP Server via opencode.json

For headless environments, CI pipelines, or infrastructure-as-code workflows, you can declare MCP servers directly in JSON configuration.

Locating the Configuration File

OpenWork reads MCP configurations from opencode.json located at either:

• Your workspace root (./opencode.json)
• The hidden .opencode directory (.opencode/opencode.json)

The application loads these configurations at startup, merging workspace-specific settings with global defaults.

MCP Server Configuration Schema

Add a new entry under the top-level mcp key using the schema defined in packages/types/src/mcp.d.ts. The minimal required fields are type, enabled, and url:

{
  "mcp": {
    "my-custom-server": {
      "type": "remote",
      "enabled": true,
      "url": "https://my-company.com/mcp/agent",
      "oauth": {
        "client_id": "your-client-id",
        "scopes": ["read", "write"]
      }
    }
  }
}

Set enabled to false to disable a server without removing its configuration. The oauth object is optional but required for endpoints that enforce OAuth 2.0 authentication.

Reloading OpenWork to Apply Changes

After saving opencode.json, restart OpenWork to reload the configuration. If running the development server, execute:

pnpm dev

The application will parse the updated configuration and expose the new MCP server to all connected agents.

Verifying the MCP Connection

Confirm successful registration by listing available capabilities from an MCP-compatible client:

# Using OpenCode CLI

openwork mcp list

# Or with Codex

codex mcp list

Programmatic verification using the OpenWork TypeScript client:

import { OpenWorkClient } from '@openwork/openwork-client';

const client = new OpenWorkClient();
const capabilities = await client.searchCapabilities({ 
  source: 'mcp:my-custom-server' 
});
console.log(capabilities);

If OAuth is configured, the first capability search triggers the authentication handshake; subsequent calls use cached credentials. For details on starting the built-in MCP server via CLI, see [.opencode/skills/shadcn/mcp.md](https://github.com/different-ai/openwork/blob/dev/.opencode/skills/shadcn/mcp.md).

Summary

• OpenWork desktop UI: Navigate to Settings → Extensions → MCP, click Add MCP Server, enter the URL, and save. Enable Show hidden to access the MCP section.
• Configuration file: Edit opencode.json in your workspace root or .opencode/ directory, add a server entry under the mcp key with type: "remote", and restart.
• OAuth support: Both methods support OAuth 2.0 flows; the UI handles browser-based authentication automatically while config-based setups may require initial manual token exchange.
• Verification: Use openwork mcp list or the OpenWorkClient.searchCapabilities() method to confirm connectivity.
• Source locations: Implementation details reside in [docs/mcp-ui-control-profile.md](https://github.com/different-ai/openwork/blob/dev/docs/mcp-ui-control-profile.md), [docs/external-mcp-oauth.md](https://github.com/different-ai/openwork/blob/dev/docs/external-mcp-oauth.md), and packages/types/src/mcp.d.ts.

Frequently Asked Questions

Where is the opencode.json file located in OpenWork?

OpenWork searches for opencode.json in two locations: the workspace root directory and the hidden .opencode folder within your project. The workspace-level configuration overrides global settings, allowing you to scope MCP servers to specific projects.

Does OpenWork support OAuth for MCP servers?

Yes. OpenWork implements OAuth 2.0 for MCP authentication. When you add a server requiring OAuth through the UI, OpenWork automatically launches a browser window to complete registration and stores tokens securely. For config-based setups, include OAuth parameters in the oauth object within your opencode.json entry.

Can I add multiple MCP servers to the same OpenWork instance?

Absolutely. You can register any number of MCP servers. In the UI, repeat the Add MCP Server process for each endpoint. In opencode.json, add multiple entries under the mcp object with unique keys. Each server maintains independent connection pools and authentication states.

What is the difference between UI-based and config-based MCP registration?

UI-based registration provides immediate activation and guided OAuth flows without file editing, ideal for development and testing. Config-based registration via opencode.json persists server definitions in version control, enables headless deployment, and supports CI/CD pipelines where graphical interaction is impossible.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}