---
title: "Deploy OpenCode MCP"
description: "Add local and remote MCP tools to hosted OpenCode"
category: "AI/ML"
url: https://railway.com/deploy/deploy-opencode-with-mcp-servers
---

# Deploy OpenCode MCP

Add local and remote MCP tools to hosted OpenCode

**[Deploy OpenCode MCP on Railway](https://railway.com/template/deploy-opencode-with-mcp-servers)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-opencode-with-mcp-servers/manifest.json

- **Creator:** onepush
- **Category:** AI/ML

## Template content

### opencode

- **Image:** ghcr.io/onepush-dev/opencode:1.19.3@sha256:9a248429018cfcec9e51416ae5e85c78c45bb6c4b9e61141d7f18e435bedd6a3
- **Health check:** /site.webmanifest
- **Public domain:** Yes

## Documentation

# Deploy and Host self hosted OpenCode MCP (Open-Source AI Coding Agent) on Railway

This template hosts OpenCode on Railway with a volume-backed home, so MCP config in opencode.json survives redeploys. Define local command arrays or remote URLs under the mcp key, toggle with enabled, and mind context cost.

## About Hosting OpenCode MCP open-source software on Railway (self hosted OpenCode template)

This template runs `opencode serve` on one Railway container, mounting a volume at `/data`. Your `opencode.json`, MCP tokens, git config, and project files all live there, so redeploys never wipe your setup or OAuth tokens.

## Why Deploy OpenCode MCP, the Claude Code alternative on Railway (Railway Free Trial)

Claude Code locks you into Anthropic billing and their hosted agent; this template gives you a container you control, with MCP servers defined in your own opencode.json, and Railway's $5 trial covers a month of light experimentation before you pay for compute.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying OpenCode MCP on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

### Railway vs Other Hosting Providers and VPS for OpenCode MCP self hosting

Railway gives you a prebuilt container with a persistent volume for MCP config; other hosts make you wire it up yourself.

| Provider | What You Get with Railway | What You Get with the Other Provider |
|---|---|---|
| DigitalOcean | One-click template, volume for MCP, Railway variables | Manual Droplet: install, systemd, HTTPS, disk |
| AWS | Managed service, auth, MCP config on volume | ECS/EC2: VPC, IAM, Docker work |
| Hetzner | Turnkey UI, persistent MCP home, variables | Cheap VPS, you secure endpoint, manage state |

You still pay for container uptime on top of model API costs, no matter the host.

## Common Use Cases for hosted OpenCode MCP

- **Sentry triage:** During a debugging session, let the agent pull a Sentry issue, read the stack trace, and propose a fix without leaving the chat.
- **Context7 docs:** Point a remote server at https://mcp.context7.com/mcp so the agent looks up current library docs instead of guessing at an API.
- **Internal tools over HTTPS:** Run a company MCP server on your network and add it with headers holding a token, so the hosted agent can reach private APIs.
- **Per-agent tool sets:** Give a review agent read-only GitHub tools and a build agent full repo write tools using agent.NAME.tools, keeping context lean.
- **Read-only database access:** Attach a local or remote DB MCP so the agent can run SELECT queries to inspect schema and data before editing code.

## Dependencies for OpenCode MCP Docker hosted on Railway

The template runs ghcr.io/onepush-dev/opencode:1.19.3 on port 4096 with one volume at /data. For MCP, opencode.json lives at /data/home/.config/opencode, and local servers need their runtime inside the container (Node ships for npx), while remote servers only need an HTTPS URL.

### Deployment Dependencies for Managed OpenCode MCP Service (AI Coding Agent)

Port 4096 is public; /data volume persists workspace and HOME. Required env: OPENCODE_SERVER_PASSWORD, OPENCODE_HOSTNAME=0.0.0.0, HOME=/data/home, OPENCODE_WORKSPACE=/data/workspace, OPENCODE_DISABLE_AUTOUPDATE=true. Health check hits /site.webmanifest.

### Implementation Details for OpenCode MCP (Using OpenCode official docker image)

Volume keeps /data/workspace and /data/home, so MCP config and OAuth tokens in mcp-auth.json persist. Tool names are prefixed with server name; disable heavy servers via tools key with globs. OAuth auto-registers on 401; run opencode mcp auth NAME to trigger.

## How does OpenCode MCP compare against other AI coding agents

### OpenCode vs Claude Code (Claude Code Alternative)

- **MCP config:** OpenCode uses opencode.json with glob disabling; Claude Code uses CLI commands.
- **Models:** OpenCode works with 75+ providers; Claude Code is Anthropic only.
- **Hosting:** OpenCode has a web UI on Railway; Claude Code is terminal-first.
- **Claude Code wins:** Deeper Anthropic integration and prompt caching.

### OpenCode vs Cursor (Cursor Alternative)

- **Hosting:** OpenCode runs in a container; Cursor is a local desktop app.
- **MCP scoping:** OpenCode disables tools per agent with globs; Cursor is IDE-centric.
- **License:** OpenCode is MIT; Cursor is proprietary and closed source.
- **Cursor wins:** Inline edits and refactoring feel faster in a full IDE.

### OpenCode vs Cline (Cline Alternative)

- **Deployment:** OpenCode is a standalone service; Cline is a VS Code extension.
- **MCP management:** OpenCode stores MCP config in one opencode.json; Cline uses VS Code settings.
- **Persistence:** OpenCode keeps MCP OAuth tokens on /data; Cline stores state locally.
- **Cline wins:** Tighter VS Code diff views and editor context.

### OpenCode vs Codex CLI (Codex CLI Alternative)

- **MCP support:** OpenCode has first-class MCP config; Codex CLI is more limited.
- **Interface:** OpenCode includes a web UI and HTTP API; Codex CLI is terminal only.
- **Providers:** OpenCode supports many providers; Codex CLI is optimized for OpenAI.
- **Codex CLI wins:** Simpler setup for OpenAI users who want a lightweight terminal agent.

## How to use OpenCode MCP (the OSS AI coding agent)?

1. Sign in to the web UI with username `opencode` and the generated password from Variables.
2. Open a shell via Railway service shell or let the agent edit files.
3. Create `/data/home/.config/opencode/opencode.json` with an `mcp` block:
```json
{"$schema":"https://opencode.ai/config.json","mcp":{"context7":{"type":"remote","url":"https://mcp.context7.com/mcp","enabled":true},"my-local":{"type":"local","command":["npx","-y","some-mcp-package"],"enabled":true}},"tools":{"github*":false}}
```
4. Start a new session and ask the agent to use the tool by name, for example "search context7 for React hooks".
5. Run `opencode mcp list` to check status, then `opencode mcp debug NAME` if needed.
6. Disable heavy tools with the `tools` key and globs like `"github*": false` to save context.

## How to self host OpenCode MCP on other VPS Services (OpenCode self hosting guide)

### Clone the Repository

You don't clone a repo for the server itself. Install OpenCode from the official install script or npm:

```bash
curl -fsSL https://opencode.ai/install | bash
```

Or use the Docker image ghcr.io/anomalyco/opencode.

### Install Dependencies

The binary bundles its runtime. If you want MCP servers that run locally, install Node.js so commands like `npx -y some-mcp-package` work, plus any language runtimes your servers need.

### Configure Environment Variables

Set a server password and hostname, then point HOME at a writable directory so config and MCP auth tokens persist:

```bash
export OPENCODE_SERVER_PASSWORD=your-password
export OPENCODE_HOSTNAME=0.0.0.0
export HOME=/home/opencode
```

### Start the OpenCode MCP Application

Run the server on port 4096 and put it behind HTTPS:

```bash
opencode serve --hostname 0.0.0.0 --port 4096
```

Railway handles the container, volume, TLS, and keeping your MCP config and tokens across redeploys.

## Official Pricing of OpenCode MCP (OpenCode pricing)

OpenCode MCP is free and open source. A container typically runs $5-15 per month at light use, more during heavy builds or tests. OpenCode Zen is an optional pay-as-you-go gateway with a few free models, but your own provider keys bill you directly. MCP servers add no separate charge unless a remote server needs its own key.

## OpenCode MCP cloud vs self hosted comparison (Pricing, features, costs, and more)

Self hosting OpenCode MCP on Railway means you own the server and the config; you pay only for compute and model API calls.

### Monthly cost of self hosting OpenCode MCP on Railway

One container on Railway runs about $5-15/mo at light use, more during heavy builds or tests. Model API costs are separate if you don't use free models; the Railway $5 trial covers early testing. Heavy builds with multiple MCP servers can push that much higher too.

### System Requirements for Hosting OpenCode MCP on a VPS

Any Linux VPS with 1 vCPU, 1 GB RAM, and 5 GB disk runs OpenCode itself. If you add local MCP servers, install their runtimes (Node.js for npx packages) and add RAM; remote MCP servers add only network latency.

## Frequently Asked Questions (FAQs)

### Where does the MCP config live on this template?

The global file is /data/home/.config/opencode/opencode.json on the volume, and a project file in /data/workspace can add more servers. Both survive redeploys.

### What is the difference between local and remote MCP servers?

A local server runs a command array like npx inside the container, while a remote server points at a url and can send headers or use OAuth. Local servers need their runtime installed in the image.

### How are OAuth tokens for remote servers stored?

OpenCode handles a 401 by doing dynamic client registration, then saves tokens to /data/home/.local/share/opencode/mcp-auth.json. That path sits on the volume, so tokens persist across redeploys.

### Why does the agent ignore a tool?

Check that the server is enabled and listed by opencode mcp list. Tools are also prefixed by server name, and a global tools block can disable matching globs like my-mcp*.

### How do I limit context bloat from MCP tools?

Disable heavy servers or tool patterns in the tools key, or set enabled false for servers you rarely use. The GitHub MCP server is a known context hog.

### Can each agent have different MCP tools?

Yes, you can re-enable disabled tool globs under agent.NAME.tools so a review agent sees a read-only set while a build agent gets more tools.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/deploy-opencode-with-mcp-servers