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

> Learn to add a new MCP server to OpenWork using the UI or by configuring opencode.json. Follow these gui and config methods for a streamlined setup.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-07-31

---

**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`](https://github.com/different-ai/openwork/blob/main/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/main/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/main/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`](https://github.com/different-ai/openwork/blob/main/opencode.json) located at either:
- Your **workspace root** ([`./opencode.json`](https://github.com/different-ai/openwork/blob/main/./opencode.json))
- The hidden **`.opencode`** directory ([`.opencode/opencode.json`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/packages/types/src/mcp.d.ts). The minimal required fields are `type`, `enabled`, and `url`:

```json
{
  "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`](https://github.com/different-ai/openwork/blob/main/opencode.json), restart OpenWork to reload the configuration. If running the development server, execute:

```bash
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:

```bash

# Using OpenCode CLI

openwork mcp list

# Or with Codex

codex mcp list

```

Programmatic verification using the OpenWork TypeScript client:

```typescript
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/main/.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`](https://github.com/different-ai/openwork/blob/main/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/main/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/main/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`](https://github.com/different-ai/openwork/blob/main/packages/types/src/mcp.d.ts).

## Frequently Asked Questions

### Where is the opencode.json file located in OpenWork?

OpenWork searches for [`opencode.json`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/opencode.json) persists server definitions in version control, enables headless deployment, and supports CI/CD pipelines where graphical interaction is impossible.