OpenCodeCAUTION
mcp/alaeddinemessadi/opencode
MCP server for OpenCode AI — 70 tools, 10 resources, 5 prompts. Use npx opencode-mcp with Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP client.
Verdict
CAUTION
Grade
B
Trust score
89 /100
Exposed tools
86 68r · 16w · 2d
Transport
stdio
License
MIT
Stars
145
01
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.npmjs.com/package/opencode-mcp) [](LICENSE) [](https://nodejs.org/)
Delegate coding work to OpenCode from your MCP client.
opencode-mcp connects Claude, Cursor, VS Code, and other MCP clients to OpenCode's headless API. Ask questions, implement features, monitor background work, respond to questions and permissions, and review changes across projects.
Version 3.0.0 requires Node.js 22 or newer. Upgrading from 2.x? See the migration notes.
Quick Start
Install OpenCode and start its server from your project:
opencode serve --hostname 127.0.0.1 --port 4096
If you use the TUI, start it with opencode --port 4096 and share that server. Set OPENCODE_BASE_URL for another endpoint.
For Claude Code:
claude mcp add opencode -- npx -y opencode-mcp
For clients using an mcpServers configuration:
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"]
}
}
}Restart the client and call opencode_setup. Choose a provider from its configured providers, then use opencode_provider_models to select a model. Set OPENCODE_DEFAULT_PROVIDER and OPENCODE_DEFAULT_MODEL together or pass the selected IDs in each prompt call.
Client-specific configuration includes VS Code, Windsurf, Continue, Zed, and Amazon Q. To test unreleased changes, build from source and configure your client to run node with the absolute path to dist/index.js.
Choose a Workflow
Read from source at commit
aa814d1c2a88OBSERVED · 2026-10-0702
Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude-code
claude mcp add opencode-mcp --env OPENCODE_SERVER_PASSWORD=${OPENCODE_SERVER_PASSWORD} -- npx -y [email protected]claude-desktop
{
"mcpServers": {
"opencode-mcp": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"OPENCODE_SERVER_PASSWORD": "${OPENCODE_SERVER_PASSWORD}"
}
}
}
}03
Exposed tools (86)
68 read · 16 write · 2 destructive. Blast radius: 2 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
build | read | Build agent |
opencode_agent_list | read | List all available agents with their names, descriptions, and modes (primary/subagent) |
opencode_ask | read | Ask OpenCode a question in one step. Creates a new session, sends your prompt, and returns the AI response. This is the easiest way to interact with OpenCode. |
opencode_auth_set | write | Set authentication credentials for a provider (e.g. API key). Credentials are stored globally and shared across all projects. |
opencode_check | read | Get current task status, pending input, todos and file counts. Uses session summary metadata instead of fetching patches. Pass jobId for exact durable turn correlation; detailed includes response text. |
opencode_command_execute | write | Execute a slash command in a session (e.g. /init, /undo, /redo) |
opencode_command_list | read | List all available commands (built-in and custom slash commands) |
opencode_config_get | read | Get the current opencode configuration |
opencode_config_providers | read | List all configured providers and their default models |
opencode_config_update | write | Update the opencode configuration. Pass a partial config object with fields to update. |
opencode_context | read | Get full project context in one call: current project, path, VCS info, config, and available agents. Useful to understand the current state before starting work. |
opencode_conversation | read | Get the full conversation history of a session, formatted for easy reading. Shows all messages with their roles and content. |
opencode_events_poll | read | Poll project events from OpenCode, or explicitly select global scope. Collects up to maxEvents within the duration. Connection failures are reported with any partial events; stopping observation does not abort remote work. |
opencode_file_list | read | List files and directories at a path |
opencode_file_read | read | Read the content of a file |
opencode_file_status | read | Get status for tracked files (VCS changes: modified, added, deleted, etc.) |
opencode_find_file | read | Find files and directories by name (fuzzy match) |
opencode_find_symbol | read | Find workspace symbols by name (functions, classes, variables, etc.) |
opencode_find_text | read | Search for text patterns in project files (regex supported). Returns file paths, line numbers, and matching lines. |
opencode_fire | read | Dispatch a durable background task and return its job, session and message IDs immediately. Use opencode_check or opencode_wait to observe; job_cancel stops the task. |
opencode_formatter_status | read | Get the status of configured formatters |
opencode_health | read | Check server health and version |
opencode_instance_dispose | read | Dispose the current opencode instance (shuts it down). WARNING: This is destructive and will terminate the server. |
opencode_job_input | read | Respond to a job |
opencode_job_list | read | List locally retained jobs in this OpenCode server and credential scope. |
opencode_log | write | Write a log entry to the opencode server |
opencode_lsp_status | read | Get the status of LSP (Language Server Protocol) servers |
opencode_mcp_add | write | Add an MCP server dynamically to opencode |
opencode_mcp_status | read | Get the status of all MCP servers configured in opencode |
opencode_message_get | read | Get details of a specific message in a session |
opencode_message_list | read | List all messages in a session with formatted output showing roles and content |
opencode_message_send | write | Send a prompt message to a session and wait for the AI response. Use parts to send text, and optionally specify a model. |
opencode_message_send_async | write | Send a prompt asynchronously and return its messageId. Pass sessionId and messageId to opencode_wait to observe this exact turn. |
opencode_path_get | read | Get the current working path of the opencode server |
opencode_permission_list | read | List all pending permission requests across all sessions. When a session is blocked waiting for approval (e.g. to run a shell command or access a file outside the project), it appears here. Respond with |
opencode_project_current | read | Get the current active project |
opencode_project_init | read | |
opencode_project_list | read | List all projects known to the opencode server |
opencode_provider_auth_methods | read | Get available authentication methods for all providers |
opencode_provider_list | read | List all configured providers with their connection status. Returns a compact summary — use opencode_provider_models to see models for a specific provider. |
opencode_provider_models | read | List available models for a specific provider. Call opencode_provider_list first to see provider IDs. |
opencode_provider_oauth_authorize | write | Start OAuth authorization for a provider |
opencode_provider_oauth_callback | read | Handle OAuth callback for a provider |
opencode_provider_test | read | Quick-test whether a provider is working. Creates a temporary session, sends a trivial prompt, checks the response, and cleans up. Great for debugging auth issues. |
opencode_question_list | read | List pending OpenCode questions, optionally filtered to a session. |
opencode_question_reject | read | Reject a pending OpenCode question explicitly. |
opencode_question_reply | read | Answer an OpenCode question request. Supply one array of selected labels or free text per question. |
opencode_reply | write | Send a follow-up message to an existing session. Use this to continue a conversation started with opencode_ask or opencode_session_create. |
opencode_review_changes | read | Get a formatted summary of all file changes made in a session. Shows diffs in a readable format. |
opencode_run | write | Send a task and wait for its correlated response. Returns a durable job ID; an observation timeout leaves the remote job running and can be resumed with opencode_wait. |
opencode_session_abort | read | Abort a running session |
opencode_session_children | read | Get child sessions of a session |
opencode_session_create | write | Create a new session. Optionally provide a parentID to create a child session, and a title. |
opencode_session_delete | destructive | Delete a session and all its data |
opencode_session_diff | read | Get the diff for a session, optionally for a specific message |
opencode_session_fork | read | Fork an existing session, optionally at a specific message |
opencode_session_get | read | Get details of a specific session by ID |
opencode_session_init | write | Analyze the app and create AGENTS.md for a session. NOTE: This is a long-running operation that may take 30-60+ seconds depending on project size. |
opencode_session_list | read | List all sessions |
opencode_session_permission | read | Respond to a permission request in a session. Use |
opencode_session_revert | read | Revert a message in a session |
opencode_session_search | read | Search sessions by keyword in title. Useful for finding a specific session among many. |
opencode_session_share | read | Share a session publicly |
opencode_session_status | read | Get status for all sessions (running, idle, etc.) |
opencode_session_summarize | read | Summarize a session using a specified model. NOTE: This is a long-running operation that may take 30-60+ seconds. |
opencode_session_todo | read | Get the todo list for a session |
opencode_session_unrevert | read | Restore all reverted messages in a session |
opencode_session_unshare | read | Unshare a previously shared session |
opencode_session_update | write | Update session properties (e.g. title) |
opencode_sessions_overview | read | Get a quick overview of all sessions with their titles and status. Useful to find which session to continue working in. |
opencode_setup | read | Check OpenCode status, provider configuration, and optionally initialize a project directory. Use this as the first step when starting work — it tells you what is ready and what still needs configuration. |
opencode_shell_execute | write | Run a shell command through the opencode session |
opencode_status | read | Get a quick status dashboard: server health, provider count, session count, and VCS info. Lighter than opencode_setup — good for at-a-glance checks. |
opencode_tool_ids | read | List all available tool IDs that the LLM can use (experimental) |
opencode_tool_list | read | List tools with JSON schemas for a given provider and model (experimental) |
opencode_tui_append_prompt | read | Append text to the TUI |
opencode_tui_clear_prompt | destructive | Clear the current prompt text in the TUI |
opencode_tui_execute_command | write | Execute a slash command through the TUI (e.g. |
opencode_tui_open_help | read | Open the help dialog in the TUI |
opencode_tui_open_models | read | Open the model selector in the TUI |
opencode_tui_open_sessions | read | Open the session selector in the TUI |
opencode_tui_open_themes | read | Open the theme selector in the TUI |
opencode_tui_show_toast | read | Show a toast notification in the TUI |
opencode_tui_submit_prompt | write | Submit the current prompt in the TUI (equivalent to pressing Enter) |
opencode_vcs_info | read | Get VCS (version control) info for the current project (branch, remote, status) |
opencode_wait | read | Wait for a session or durable job. Returns completed, failed, input_required, or a resumable timeout. Cancelling this wait stops observation; use job_cancel or session_abort to stop OpenCode. |
04
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (3 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (10)
MEDIUMNetwork egress · net.raw_ip · CWE-200, CWE-319
src/helpers.ts:622
tips.push("- Verify OPENCODE_BASE_URL is correct (default: http://127.0.0.1:4096)");MEDIUMFilesystem / path · mcp.destructive_tools · CWE-22, CWE-59
opencode_session_delete, opencode_tui_clear_prompt
Why it matters. 2 tool(s) can delete or overwrite
Fix. prefer a read-only mode or scoped tokens; the page states the blast radius
LOWFilesystem / path · fs.system_paths · CWE-22, CWE-59
tests/project-tool.test.ts:123
const result = await callInit({ path: "/etc/foo" });LOWFilesystem / path · fs.system_paths · CWE-22, CWE-59
tests/tools.test.ts:1563
patterns: ["/etc/hosts"],
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
README.md:88
| `OPENCODE_BASE_URL` | Server endpoint; defaults to `http://127.0.0.1:4096` |
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
docs/configuration.md:9
| `OPENCODE_BASE_URL` | `http://127.0.0.1:4096` | OpenCode HTTP endpoint |
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
docs/configuration.md:44
claude mcp add opencode --env OPENCODE_BASE_URL=http://127.0.0.1:8080 -- npx -y opencode-mcp
LOWNetwork egress · net.raw_ip · CWE-200, CWE-319
scripts/mcp-smoke-test.mjs:20
baseUrl: env.OPENCODE_BASE_URL ?? "http://127.0.0.1:4096",
LOWSupply chain · supply.unpinned · CWE-829, CWE-1357
package.json
@modelcontextprotocol/core, @modelcontextprotocol/server, @opencode-ai/sdk, zod, @modelcontextprotocol/client, @modelcontextprotocol/sdk, @types/node, @vitest/coverage-v8
Why it matters. 10 dependency range(s) float
Fix. pin exact versions or ship a lockfile
LOWPrompt injection · prompt.transfer_instruction · CWE-94, CWE-1427
docs/getting-started.md:72
Check its current state and pending input. Use `opencode_job_list` to rediscover tracked work after reconnecting. A server/network error or `unknown` state is not a reason to submit the same prompt ag
Why it matters. an instruction to move sensitive data to an outside destination
Fix. remove; a skill never needs the user's secrets off the machine
Gates applied: no_behavioural_pass.
Audited 2026-10-07 · audit v0.4.1 · source sha
aa814d1c2a88full audit observations/trust-audit/mcp-server/alaeddinemessadi__opencode.json · Report an issue / request a re-scan05
Audit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | aa814d1c2a88 | CAUTION | B | 89 | first audit |
06
Questions
What is the OpenCode MCP server?
MCP server for OpenCode AI — 70 tools, 10 resources, 5 prompts. Use npx opencode-mcp with Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP client.
What tools does OpenCode expose?
86 in total: 68 read-only, 16 that write, and 2 that can delete or overwrite (opencode_session_delete, opencode_tui_clear_prompt). Every one is listed on this page with its risk.
Is OpenCode safe to connect to an agent?
With care. The audit graded it B (89/100) and found 10 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 2 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does OpenCode need?
It reads OPENCODE_SERVER_PASSWORD from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does OpenCode run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as opencode-mcp at 3.0.0.
How current is this page?
The grade is for one exact copy of the source (aa814d1c2a88), read on 2026-10-07. The repository is watched and re-audited when it changes.