Back to Recipes

Local OpenCode Agent Workspace

Set up a local OpenCode agent workspace with custom MCP servers, tool permissions, and project-specific instructions.

Best for: Developers building custom AI agent workspaces

What You Get

  • -OpenCode workspace configuration
  • -MCP server setup with custom tools
  • -Tool permission management
  • -Project-specific system prompts
  • -Workspace sharing and versioning

Step by Step

1. Create the workspace directory

Create a directory structure: .opencode/ with subfolders for config, tools, and prompts. Initialize a git repo so the workspace is version-controlled and shareable.

2. Configure opencode.json

Create opencode.json with: agent name, model settings (provider, model name, temperature), allowed tools list (bash, read, write, edit, glob, grep), and reference to the system prompt file.

3. Add MCP servers

Configure MCP servers in the workspace: filesystem server for project file access, database server for querying the project DB, and web search server for research. Each server gets its own config block with command, args, and env vars.

4. Set tool permissions

Create a permissions config: allow read/write for project source files, allow bash for npm/bun/git/test commands only, block access to .env and node_modules directories, allow web search and database read-only queries.

5. Test the agent

Run OpenCode in the workspace and test: 'Read the project structure', 'Show me the dependencies', 'What is the main entry point?', 'Run the tests'. Verify MCP servers are connected and permissions work.

Stack

OpenCodeMCP SDKNode.jsTypeScriptVS Code / Cursor

Build This

Copy this prompt and paste it into Claude Code, OpenCode, Codex, or Cursor to build this recipe.

Build me a local OpenCode agent workspace. It should: 1) Create a workspace directory with opencode.json config file. 2) Configure MCP servers for file system access, database queries, and web search. 3) Set tool permissions: allow read for all project files, allow bash for npm/bun/git commands, block access to .env and node_modules. 4) Add a project-specific system prompt describing the codebase and coding conventions. 5) Include quick-start instructions and a test command to verify the agent works. The workspace should be portable so other team members can clone and use it.

Common Failure Modes

  • !MCP server connection errors
  • !Permission misconfiguration blocks needed tools
  • !System prompt too verbose causes slow responses
  • !LLM API key not configured

Implementation Notes

Start with a minimal config and add tools gradually. Test each MCP server individually before adding the next. Keep the system prompt under 500 words.

Want local opencode agent workspace running in your business?

4M Labs can deploy local opencode agent workspace as a production workflow:

  • Connected to your tools and data sources
  • Secured for your team with proper access controls
  • Deployed with monitoring and error handling
  • Documented for handoff and future maintenance
Book an Implementation Sprint