MCP Integration

MCP (Model Context Protocol) allows AI agents to use external tools and services. 1Code provides full MCP server lifecycle management with a built-in plugin marketplace.

Why It Matters

AI agents have limited built-in capabilities:

Can’t access databases
Can’t call external APIs
Can’t integrate with third-party services
Can’t use specialized tools

MCP solves this by providing a standard protocol for agents to:

Query databases (PostgreSQL, MySQL, MongoDB)
Call APIs (GitHub, Linear, Slack, Stripe)
Use dev tools (Docker, Kubernetes, AWS CLI)
Access specialized services (vector DBs, search engines)

What is MCP?

MCP is an open protocol that defines how AI agents communicate with external tools. Architecture:

AI Agent <--> MCP Client <--> MCP Server <--> External Service

Example MCP Server: A GitHub server exposes tools like:

create_issue - Create a GitHub issue
list_pull_requests - List PRs for a repo
merge_pull_request - Merge a PR

The agent can call these tools just like built-in tools (bash, edit, etc.).

Installing MCP Servers

From the Plugin Marketplace

Open Marketplace

Go to Settings → Plugins → Browse Marketplace

Find a Plugin

Search for plugins by name or category (databases, APIs, dev-tools)

Install

Click “Install” - 1Code downloads and configures the server automatically

Enable

Toggle the server on in Settings → Plugins → Installed

Installed servers appear in the MCP Widget in the sidebar.

Manual Installation

For custom servers not in the marketplace: Stdio Servers:

# 1. Install the server
npm install -g @my-org/custom-mcp-server

# 2. Add to 1Code
# Settings → Plugins → Add Server
# Type: stdio
# Command: custom-mcp-server
# Args: --config /path/to/config.json

HTTP Servers:

# 1. Start the server
docker run -p 8080:8080 my-mcp-server

# 2. Add to 1Code
# Settings → Plugins → Add Server
# Type: HTTP
# URL: http://localhost:8080

Implementation: The plugins router (src/main/lib/trpc/routers/plugins.ts:175) scans installed plugins and discovers their MCP servers. The MCP Widget shows all active servers and their tools.

Server List

Each server displays:

Name and icon
Number of available tools
Status indicator (connected, failed, needs-auth)
Expand to see tools

Example:

📊 PostgreSQL (5 tools)
  - query_database
  - list_tables
  - describe_table
  - create_table
  - drop_table

🐙 GitHub (12 tools)
  - create_issue
  - list_pull_requests
  - merge_pull_request
  ...

Using Tools

Click any tool to insert an @ mention:

@postgres:query_database

The agent will use that tool when executing your prompt. Widget Implementation: The MCP Widget (src/renderer/features/details-sidebar/sections/mcp-widget.tsx:65) groups tools by server and formats tool names for readability.

Configuring MCP Servers

Server Settings

Each server can have custom configuration: Example: PostgreSQL

{
  "host": "localhost",
  "port": 5432,
  "database": "myapp_dev",
  "user": "postgres"
}

Example: GitHub

{
  "defaultRepo": "my-org/my-repo",
  "includePrivate": true
}

Access server settings:

Settings → Plugins → Installed
Click the gear icon next to a server
Edit JSON configuration
Save - server restarts automatically

Environment Variables

Servers often need secrets (API keys, passwords). Store them as env vars:

# .env
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
STRIPE_API_KEY=sk_test_xxxxxxxxxxxx
DATABASE_PASSWORD=xxxxxxxxxxxx

Reference in server config:

{
  "apiKey": "${GITHUB_TOKEN}"
}

1Code loads .env files from:

Project root (.env)
User home (~/.1code/.env)
System environment

Authentication

Some servers require OAuth or bearer tokens. OAuth Servers: Click “Login” in the server settings to start OAuth flow. Example: Linear

Click “Login” next to Linear server
Browser opens to Linear’s OAuth page
Approve permissions
Return to 1Code - server is now authenticated

Token Servers: Provide a bearer token in settings:

{
  "bearerToken": "${LINEAR_API_KEY}"
}

Creating Custom MCP Servers

Server Types

Stdio
HTTP

Communicates via stdin/stdout. Best for local tools.

import { MCPServer } from '@modelcontextprotocol/sdk'

const server = new MCPServer({
  name: 'my-custom-server',
  version: '1.0.0'
})

server.addTool({
  name: 'hello',
  description: 'Says hello',
  parameters: {
    name: { type: 'string' }
  },
  execute: async ({ name }) => {
    return `Hello, ${name}!`
  }
})

server.listen()

Exposes tools via HTTP endpoints. Best for remote services.

import express from 'express'
import { MCPHttpAdapter } from '@modelcontextprotocol/sdk'

const app = express()
const mcp = new MCPHttpAdapter({
  name: 'my-http-server',
  version: '1.0.0'
})

mcp.addTool({
  name: 'search',
  description: 'Search the database',
  parameters: {
    query: { type: 'string' }
  },
  execute: async ({ query }) => {
    // Call your database or API
    return results
  }
})

app.use('/mcp', mcp.router())
app.listen(8080)

Publishing to Marketplace

Create a plugin package:

{
  "name": "@my-org/my-plugin",
  "version": "1.0.0",
  "1code": {
    "type": "plugin",
    "mcp-servers": {
      "my-server": {
        "type": "stdio",
        "command": "my-server",
        "description": "Does something useful"
      }
    }
  }
}

Publish to npm:

npm publish

Submit to marketplace:

Go to https://1code.dev/marketplace/submit
Enter your package name
Fill in description, category, tags
Submit for review

Use Cases

Database Operations

Query PostgreSQL, MySQL, MongoDB directly from chat. No manual SQL needed.

API Integration

Call GitHub, Linear, Slack APIs. Create issues, send messages, deploy code.

Dev Tools

Run Docker commands, deploy to Kubernetes, manage AWS resources.

Custom Workflows

Build company-specific tools. Internal APIs, deployment scripts, etc.

Popular MCP Servers

Official Servers

@modelcontextprotocol/server-postgres - PostgreSQL queries
@modelcontextprotocol/server-github - GitHub API
@modelcontextprotocol/server-slack - Slack messaging
@modelcontextprotocol/server-google-drive - Google Drive access

Community Servers

@mcp/linear - Linear issue management
@mcp/stripe - Stripe payment operations
@mcp/docker - Docker container management
@mcp/aws - AWS CLI wrapper

Browse all at https://1code.dev/marketplace/plugins

Codex MCP Support

Codex has enhanced MCP support with additional features:

Global vs Project Servers

Global Servers: Available to all chats (configured in ~/.codex/config.toml). Project Servers: Available only to chats in a specific project (configured in <project>/.codex/config.toml). Codex automatically discovers both and merges them.

MCP CLI

Codex provides a CLI for managing servers:

# List servers
codex mcp list

# Add a server
codex mcp add my-server -- my-server-command --arg

# Remove a server
codex mcp remove my-server

# Login to OAuth server
codex mcp login my-server

1Code uses this CLI internally to manage Codex MCP servers.

Best Practices

Use Scoped Servers

Install database/API servers per-project, not globally. Prevents accidental access to wrong data.

Version Pin Dependencies

Pin MCP server versions in package.json to avoid breaking changes.

Test Locally First

Before using in chat, test server tools manually with mcp-cli.

Monitor Tool Usage

Check Settings → Debug → MCP Logs to see which tools agents are calling.

Troubleshooting

Server shows 'needs-auth'

Cause: OAuth or bearer token required.Fix:

Click “Login” in server settings
Or add bearerToken to config
Or set environment variable with token

Server shows 'failed'

Cause: Server command not found or crashed on startup.Fix:

Check that the server binary is installed (which <command>)
View logs in Settings → Debug → MCP Logs
Try running the command manually to see errors

Tools not appearing in MCP Widget

Agent not using MCP tools

Cause: Tools not mentioned in prompt or agent chose not to use them.Fix:

Use @ mentions to hint which tools to use
Be explicit: “Use the GitHub server to create an issue”
Check if the server is enabled in settings

Multi-Agent Support - Different agents have different MCP support levels
Visual UI - MCP tool calls are displayed in the chat UI
Background Agents - MCP servers work in cloud sandboxes too

Get Started

Core Features

Guides

Advanced

MCP Integration

Why It Matters

What is MCP?

Installing MCP Servers

From the Plugin Marketplace

Manual Installation

MCP Widget

Server List

Using Tools

Configuring MCP Servers

Server Settings

Environment Variables

Authentication

Creating Custom MCP Servers

Server Types

Publishing to Marketplace

Use Cases

Database Operations

API Integration

Dev Tools

Custom Workflows

Popular MCP Servers

Official Servers

Community Servers

Codex MCP Support

Global vs Project Servers

MCP CLI

Best Practices

Use Scoped Servers

Version Pin Dependencies

Test Locally First

Monitor Tool Usage

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Advanced

Documentation Index

​Why It Matters

​What is MCP?

​Installing MCP Servers

​From the Plugin Marketplace

​Manual Installation

​MCP Widget

​Server List

​Using Tools

​Configuring MCP Servers

​Server Settings

​Environment Variables

​Authentication

​Creating Custom MCP Servers

​Server Types

​Publishing to Marketplace

​Use Cases

Database Operations

API Integration

Dev Tools

Custom Workflows

​Popular MCP Servers

​Official Servers

​Community Servers

​Codex MCP Support

​Global vs Project Servers

​MCP CLI

​Best Practices

Use Scoped Servers

Version Pin Dependencies

Test Locally First

Monitor Tool Usage

​Troubleshooting

​Related Features

Build docs developers (and LLMs) love

Why It Matters

What is MCP?

Installing MCP Servers

From the Plugin Marketplace

Manual Installation

MCP Widget

Server List

Using Tools

Configuring MCP Servers

Server Settings

Environment Variables

Authentication

Creating Custom MCP Servers

Server Types

Publishing to Marketplace

Use Cases

Popular MCP Servers

Official Servers

Community Servers

Codex MCP Support

Global vs Project Servers

MCP CLI

Best Practices

Troubleshooting

Related Features