The user wants to add the Gemini API coding agents documentation as an MCP server to their opencode configuration. Let me first check if there's an existing opencode configuration file, and understand what MCP servers look like in opencode configs. Let me start by looking for opencode configuration files.
The user wants to add a "gemini docs" MCP server to their opencode configuration. Let me first look at their existing config file, and also check what URL they're referring to. They mentioned `https://ai.google.dev/gemini-api/docs/coding-agents` - I need to understand what MCP server they want. Let me read the current opencode config first.
The URL for Gemini docs is timing out. The user wants to add a "Gemini docs" MCP server based on the Gemini API coding agents documentation. Let me look up what MCP server or tool they might be referring to. Let me check if there's a Gemini MCP server available, or if there's a way to use the Gemini API docs as an MCP server. Let me search for what the user might be referring to. Actually, looking at this more carefully, the user said "gemini docs mcp" - this might be a reference to a specific MCP server. Let me search the web for "gemini docs mcp server" or "google gemini MCP server" to understand what they're referring to. Wait - the user linked `https://ai.google.dev/gemini-api/docs/coding-agents` and said "gemini docs mcp". This could be: 1. An MCP server that provides access to Gemini API docs 2. A reference to the Gemini MCP server from Google Let me search for this.
Now I understand! The user is referring to the **Gemini API Docs MCP server** hosted at `https://gemini-api-docs-mcp.dev`. This is a public MCP server that provides documentation search for the Gemini API.
According to the opencode config format (from the skill), MCP servers with type "remote" look like:
```json
"mcp": {
"server-name": {
"type": "remote",
"url": "https://...",
"enabled": true,
"headers": { "Authorization": "Bearer ..." }
}
}
```
For the Gemini API Docs MCP server, since it's a public MCP server at `https://gemini-api-docs-mcp.dev`, I need to add it as a remote MCP server. Let me check if it requires authentication or not. The web search result shows:
```
npx add-mcp "https://gemini-api-docs-mcp.dev"
```
This suggests it might use the `add-mcp` package, but for opencode's config format, I'll just add it as a remote MCP server with SSE or HTTP transport.
Actually, looking at it more carefully, `npx add-mcp` is a specific command for a tool that helps add MCP servers. But for opencode, the MCP config format is clear from the skill docs:
For a remote type:
```json
"mcp": {
"server-name": {
"type": "remote",
"url": "https://...",
"enabled": true,
"headers": { ... }
}
}
```
The Gemini Docs MCP is at `https://gemini-api-docs-mcp.dev`. It appears to be a public endpoint that doesn't require authentication (or at least the basic usage doesn't mention needing a key). Let me check if it needs an API key.
Looking at the search results more carefully:
- "Gemini hosts a public Model Context Protocol (MCP) server at `https://gemini-api-docs-mcp.dev`."
- The command shown is just `npx add-mcp "https://gemini-api-docs-mcp.dev"` — no auth headers mentioned.
But actually, there's also the Google Developer Knowledge MCP at `https://developerknowledge.googleapis.com/mcp` which requires authentication. The Gemini API Docs MCP appears to be separate from that one.
Let me also look at the Gemini API docs page more carefully. The web search already gave me the key info: the server is at `https://gemini-api-docs-mcp.dev`.
For opencode, I need to add a remote MCP server entry. The format for remote MCP servers in opencode is:
```json
"mcp": {
"gemini-docs": {
"type": "remote",
"url": "https://gemini-api-docs-mcp.dev",
"enabled": true
}
}
```
I'm not sure if this needs SSE, HTTP streaming, or something else. Let me check the opencode MCP config schema more closely.
Looking at the skill output:
```json
"playwright": {
"type": "local",
"command": ["npx", "-y", "@playwright/mcp"],
"enabled": true,
"env": {}
},
"remote-thing": {
"type": "remote",
"url": "https://...",
"headers": { "Authorization": "Bearer ..." }
}
```
So for remote type, the `url` field is used. It seems like opencode supports both `url` (for SSE) and potentially `httpUrl` for HTTP streaming, but the skill only shows `url`. Let me also check the JSON schema.
Actually, let me just fetch the schema quickly.Now I have a clear picture. The Gemini API Docs MCP server is at `https://gemini-api-docs-mcp.dev`. According to the opencode schema, for a remote MCP server, I need:
```json
"gemini-docs": {
"type": "remote",
"url": "https://gemini-api-docs-mcp.dev",
"enabled": true
}
```
The schema shows that `McpRemoteConfig` requires `type` and `url`, and has optional `enabled`, `headers`, `oauth`, and `timeout`.
The existing config is at `/root/.config/opencode/opencode.jsonc`. I need to add an `mcp` block with the Gemini Docs MCP server.
Let me also check if the server needs authentication. The web search results mention that it's a "public" MCP server, and the command to add it is simply `npx add-mcp "https://gemini-api-docs-mcp.dev"` without any auth headers mentioned. So it seems like it doesn't require auth.
Let me now add the MCP server to the config.The edit was applied. Now I should remind the user to restart opencode for the changes to take effect, as per the customize-opencode skill instructions.
The user wants me to: 1. Check if there's a systemd service for opencode 2. Verify the config is correct for that service 3. Restart the service Let me check the systemd service configuration and find out which config file the service uses.
The systemd service runs `opencode serve` and uses the default config loading mechanism. The environmental config is at `/etc/opencode/opencode.env`. Let me check that file to see if it specifies a custom config path.
No custom config path is set. The service uses `openocode serve` which will load the default config at `~/.config/opencode/opencode.jsonc` (or `opencode.json`) since `HOME=/root` is set. The config I edited is indeed at `/root/.config/opencode/opencode.jsonc`, so the systemd service will pick it up. Let me verify the config file is syntactically valid.
The config looks good. The systemd service uses `HOME=/root` so it will read `~/.config/opencode/opencode.jsonc` which is the file I edited. No custom config path override is set in the environment file. Let me restart the service.
The user is asking if the restart worked. My bash command was interrupted, so I didn't get the output. Let me check the status of the service now.
The user is asking if I (the opencode agent) can access the MCP server I just configured. This is a meta question about whether the MCP tool is available to me. Let me think about this...
Actually, MCP servers are configured in the opencode config, but they become available as tools for the AI model to use within the session. However, the config change I made requires a restart of opencode to take effect. Since the user restarted the systemd service, the new config should be loaded.
But wait - *I* am running in the opencode session that was started before the config change. The systemd service was restarted, but this session/agent might still be running in the old context. However, the user said "Did that work" and then "Can you access the mcp" - they're asking me to check if the MCP server is accessible.
Let me think about what tools the MCP server provides. According to the docs, the Gemini API Docs MCP adds a `search_documentation` tool. But I can't directly use that tool unless it's exposed to me through the opencode session.
Actually, I don't think MCP servers configured in opencode.json are exposed as tools to the model within the same opencode session. MCP servers are for external tools that opencode can use. The opencode MCP configuration is for when opencode itself acts as an MCP server or uses MCP servers.
Wait, looking at the opencode skill docs again:
```json
"mcp": {
"playwright": {
"type": "local",
"command": ["npx", "-y", "@playwright/mcp"],
"enabled": true,
"env": {}
},
```
MCP servers configured here become tools available to the AI model within opencode. So the `search_documentation` tool from the Gemini API Docs MCP server should be accessible to me... but only if the session has been restarted.
Since the systemd service was restarted, a new session would need to be started. But this conversation/session might be the one that was running before the restart, so I might not have the MCP tools available.
Let me try to check if the MCP server is connected by looking at what tools are available to me, or by attempting to use it somehow. Actually, I don't think there's a direct way for me to list MCP tools available to the current session.
Actually wait - the user is asking if *I* can access it. Let me just be honest - MCP servers configured in opencode.json expose their tools to the AI model in the session. If this session was started after the restart, then yes I should have them. But I don't have a way to enumerate MCP tools available to me.
Hmm, but actually, I think the MCP tools should be merged into my available tool set if the session was restarted after the config change. Since the service was restarted and the current session is running, it likely picked up the new config.
But I don't see any `search_documentation` tool in my available tools list. So either:
1. This session started before the restart
2. The MCP server isn't connected properly
3. MCP tools aren't exposed to the primary model in the way I'm thinking
Let me try a different approach - let me check if there's a way to list connected MCP servers. Actually, I can try running the opencode binary to check the config validity or see if there are any errors.
Let me try to check if the config is valid by asking opencode to validate it.The service restarted cleanly at 09:02:06 and is now running. But there's no log about MCP servers connecting. The service started and said it's listening. The MCP servers configured in opencode.json are typically loaded lazily, so they may only connect when a tool from them is actually invoked. However, this current session I'm in - I need to think about whether it's the same session that was running before the restart, or a new one. Since opencode serve is a headless server, this CLI session I'm talking to might be connected to that server. When the server was restarted, the connection may have been dropped and re-established. Actually, wait - I'm an agent running in opencode. The user is interacting with opencode, and I'm the model powering it. The opencode serve was restarted. But this particular conversation/session... hmm, I'm not sure if this is a new session or an old one. Let me just try to see if I can detect the MCP tool. I don't have a `search_documentation` tool available in my tool list. So either: 1. The session isn't connected to the restarted server 2. The MCP tool isn't accessible to me in this context But actually, looking at my available tools, I don't see a `search_documentation` tool. So either it's not available or I need to check differently. Let me try a different approach - let me see if the config is valid by asking the opencode binary itself.
The opencode CLI doesn't have an `mcp` subcommand to list MCP servers. Let me think about this differently.
Looking at the opencode config schema and skill docs again:
```json
"mcp": {
"playwright": {
"type": "local",
"command": ["npx", "-y", "@playwright/mcp"],
"enabled": true,
"env": {}
},
```
MCP servers in opencode config are meant to expose tools to the AI model. So when I have a `gemini-docs` MCP server configured, it should provide a `search_documentation` tool that I (the model) can use.
But I don't have that tool in my available tool list. This could mean:
1. The current session started before the restart (so the old config without MCP is loaded)
2. The MCP server is unreachable
3. The MCP tools are only available to subagents, not the primary agent
Actually, looking at the experimental config:
```json
"experimental": {
"primary_tools": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tools that should only be available to primary agents."
}
```
MCP tools might be restricted. But by default, they should be available.
Let me check if the old session was from before the restart. The logs show the service was stopped and restarted. If I'm in the same conversation, I might be connected to the old server that was stopped, or the new one.
Actually, I think the real issue is that the opencode serve process was restarted, but the actual session I'm in might have been re-established. Let me just try to access the MCP server's URL directly to see if it's reachable.Getting a 429 (Too Many Requests) from the Gemini Docs MCP server. That's interesting - it means the server is reachable but rate-limiting us. Let me try a different approach and see if it supports SSE by checking the endpoint's behavior. Actually, the 429 could just be because curl doesn't speak MCP protocol and the server is returning a rate limit. Let me try with a proper MCP request or just check if we can connect. But more importantly - do I have access to the MCP tools in this session? Let me look at my tool list. I don't see `search_documentation` in my tools. This means either: 1. This session is still using the old config (pre-restart) 2. The MCP server connection isn't established yet Since the opencode serve was restarted, and this conversation is happening through that server, the session should be using the new config. But I'm not seeing any MCP tools. Wait, let me reconsider. Maybe MCP tools are exposed differently - perhaps they're only available to subagents. Or maybe the `search_documentation` tool is not exposed to me directly but would be used by the system when needed. Actually, I think the issue might be that MCP tools in opencode are integrated into the tool ecosystem, but they might have specific names and might not show up in my standard tool list. Let me check if the config is syntactically valid by using jq or something similar.
Getting 429 from the MCP server. Let me try with a different approach - maybe I need to look at the actual transport mechanism. The Gemini Docs MCP might be using HTTP streaming transport (not SSE), which is a different protocol. Actually, let me step back. The 429 error might mean the server is rate-limiting. But regardless of that, the question is whether *I* (the model running in this opencode session) can access the MCP tools. Since I don't see `search_documentation` in my tool list, it seems like the MCP tools haven't been loaded into this session. This could be because: 1. opencode's MCP integration only loads tools lazily when they're first needed 2. The MCP tools are exposed to subagents only 3. There might be an issue with the config But actually, I realize the real issue might be simpler: the `opencode serve` command is running as a server, and this session might be a client connected to it. The MCP configuration in opencode.json would be loaded by the server process. So when the server was restarted, the new session should have the new config. However, I'm not sure if MCP tools from remote servers automatically become available as tools I can call, or if they work differently. Let me just check if there's an MCP-related endpoint on the opencode server itself.
That was the Gemini CLI's MCP documentation, which describes how the Gemini CLI works with MCP servers. But I need to understand how opencode works with remote MCP servers.
From the opencode schema I already fetched, the `McpRemoteConfig` shows:
```json
"McpRemoteConfig": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["remote"],
"description": "Type of MCP server connection"
},
"url": {
"type": "string",
"description": "URL of the remote MCP server"
},
"enabled": {
"type": "boolean",
"description": "Enable or disable the MCP server on startup"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Headers to send with the request"
},
"oauth": {
"anyOf": [
{"$ref": "#/$defs/McpOAuthConfig"},
{"type": "boolean", "enum": [false]}
],
"description": "OAuth authentication configuration for the MCP server. Set to false to disable OAuth auto-detection."
},
"timeout": {
"type": "integer",
"description": "Timeout in ms for MCP server requests."
}
},
"required": ["type", "url"]
}
```
So for a remote MCP server in opencode, I need to provide `type: "remote"` and `url`. The Gemini API Docs MCP is at `https://gemini-api-docs-mcp.dev` and the web search results mention it as a "public" MCP server.
Looking at the Gemini CLI docs, it supports three transport types:
- `httpUrl` - Streamable HTTP transport
- `url` - SSE transport
- `command` - Stdio transport
The Gemini API Docs MCP at `https://gemini-api-docs-mcp.dev` - I'm not sure which transport it uses. Let me try to figure this out. When I curled it, I got a 429 (rate limited), which means it's responding to HTTP requests.
In opencode's schema, the remote MCP config has a `url` field. As mentioned in the Gemini CLI docs, there are two URL-based transports:
1. `url` - SSE endpoint
2. `httpUrl` - HTTP streaming endpoint
But opencode just has one `url` field under `McpRemoteConfig`. Let me check if there's something else...
Actually, the opencode config I have is:
```json
"gemini-docs": {
"type": "remote",
"url": "https://gemini-api-docs-mcp.dev",
"enabled": true
}
```
This seems correct based on the schema. But the MCP server might not be connecting properly because:
1. The current session might be on the old config
2. The MCP server might be rate-limiting us (429)
Let me try to verify by checking if the opencode server actually sees the MCP config. Perhaps I can look at opencode's logs to see if there are MCP-related messages.
Actually, let me reconsider what the user is asking. They said "Can you access the mcp" - this might mean they want me to check if *I* as the model can use the MCP tools. Since I have the `webfetch` tool, I could try to directly call the MCP server's endpoint to verify it works.
But more practically, the issue might be that:
1. The current opencode session started with the old config (before the `mcp` block was added)
2. After the restart, the server loaded the new config, but this conversation is tied to the old session
Let me check the service restart time vs when this conversation started.
The log shows:
- Service stopped and restarted at `Jun 05 09:02:06`
- Service is now `active (running) since Fri 2026-06-05 09:02:06 UTC`
And the user asked "Did that work" and "Can you access the mcp" - so this conversation is happening after the restart.
If this is the same opencode session that was running before the restart, it might have been disconnected and reconnected. But if the conversation state persisted, it might still be using the old tools.
Regardless, I should try to verify connectivity. Let me tryThe user wants me to run `npx add-mcp "https://gemini-api-docs-mcp.dev"` which is the command from the Gemini docs to add the MCP server. This likely uses the `add-mcp` npm package to configure the MCP server. Let me run it.
The `add-mcp` tool ran but crashed at the interactive agent selection prompt because there's no TTY. It successfully detected the server source and named it `gemini-api-docs-mcp`, but then it tried to prompt interactively for agent selection and failed. Let me check what `add-mcp` actually did before crashing - it might have already written some config changes. Also, let me try running it with flags to avoid the interactive prompt. Let me check the `--help` output.
I see! I need to use `--all` or `-a` to specify which agent, and `-y` to skip confirmation prompts. Let me try with `--all` and `-y`. Also, for opencode, let me check if `add-mcp` supports it.
`add-mcp` supports `opencode` as an agent. Now I can run the command with `--agent opencode -y` or `--all -y` to avoid the interactive prompt.
It installed to `/opencode.json`. Let me check what it wrote there, and also check if the systemd service config at `/root/.config/opencode/opencode.jsonc` needs updating. The user wanted it in the systemd service's config. Let me check what was created.
OK, so the `add-mcp` tool wrote to `/opencode.json` (project-level config in the root). But the user's systemd service uses the config at `/root/.config/opencode/opencode.jsonc`. The `/opencode.json` file is in the workspace root `/`, but opencode walks up from cwd to the worktree root to find config. The systemd service has `HOME=/root` and runs from `/`, so it might or might not pick this up. Actually, looking at the skill docs: | Project config | `./opencode.json`, `./opencode.jsonc`, or `.opencode/opencode.json` (opencode walks up from the cwd to the worktree root) | Since the service's cwd is likely `/`, it would find `/opencode.json`. Configs from each scope are deep-merged. Project overrides global. But wait - I already edited the global config at `/root/.config/opencode/opencode.jsonc` to have a `gemini-docs` entry. The project config now has a `gemini-api-docs-mcp` entry with the same URL. They'll both be loaded and merged. Actually, it might be cleaner to just use the project config since `add-mcp` put it there. But actually, I need to check if `--global` would have put it in the right place. The user asked for the systemd service config. Let me check the systemd service's working directory. The service runs: ``` ExecStart=/root/.opencode/bin/opencode serve --hostname 127.0.0.1 --port 4096 ``` It doesn't set `WorkingDirectory`, so it defaults to `/`. So the project config at `/opencode.json` would be found. But actually, the user said "the opencode server that runs via systemd" - and the add-mcp tool already installed it to the right place. The systemd service should pick this up on restart. However, I have two entries now: 1. `/root/.config/opencode/opencode.jsonc` has `gemini-docs` (my manual addition) 2. `/opencode.json` has `gemini-api-docs-mcp` (from add-mcp) Both point to the same URL. This is fine - they'll be merged and both will work. But it's redundant. Let me leave it as is since `add-mcp` did its job. Now I should restart the systemd service.
**Acting on logs** I need to take action here. It’s important to inspect the logs and check the current status. Should I use a to-do list to make sure I don’t miss anything? That seems like a multi-step process, which could definitely help keep me organized. It might also be useful to track any issues that come up while I’m inspecting. Let’s get started on this!
**Considering timeout and configuration adjustments** I’m wondering if I need to add a larger timeout due to remote rate limiting since the default 5 seconds may not be enough. Increasing it to 30 seconds could be a good idea. I might want to use `add-mcp -g` for a global config instead of just a project-specific one, but I need to remember that systemd loads both configurations. I should verify the working directory by checking the process to ensure everything's set up correctly. Reading /proc/PID/cwd might help clarify if paths are an issue.
**Editing API configurations** I need to make some edits, particularly removing /opencode since the user didn't ask for this. I created this, so I want to ensure I don't revert any user changes. I'll use apply_patch to update the global name to gemini-api-docs-mcp, maybe set a timeout of 30000 and consider whether to disable OAuth auto-detection, especially since the server is public. Also, I should add "oauth": false to avoid unnecessary attempts after a 401 error.
**Checking systemd and JSON settings** I need to verify the current working directory for systemd and consider restarting it. I might also want to validate JSONC. Could I use bun for that? I remember jq doesn’t allow comments, so I should stick to pure JSON. Alternatively, I could use Node.js for parsing. I also have to think about possibly fetching an external endpoint since I might encounter a 429 error. A restart seems necessary to follow through.
**Investigating service issues** I need to keep going with this analysis. I should check if a service restart was interrupted, which might explain some issues. Maybe the opencode server has a configuration endpoint? I’ll consider using curl to explore that further and look into the documentation for clarity. It seems like I also need to check where the configuration is sourced from, particularly with the global settings. Let's confirm what the API endpoints can tell us and monitor the status as well. I’ll also need to investigate logs for any errors.
**Inspecting API endpoints** I need to take a closer look at the API to understand its endpoints. I should check the available routes using curl, maybe starting with something like /? or /config?. It might be helpful to refer to the open-source server documentation to find more details. Perhaps I could inspect the binary or even use strings to extract more info. Let's focus on known endpoints, like /doc, to get started!
**Exploring API endpoints** I need to get JavaScript assets for search endpoints. I wonder if I can use Bash with `rg` to read remotely, or if `curl` will help me save files—but file operations might be tricky. Should I use a local API instead? I think I really need to focus on finding those endpoints. Maybe I can leverage `grep` for content searches in the installed open code. I'll check the source in `/root/.opencode` and use `grep` if necessary.
**Clarifying configurations** I'm thinking the GUI project directory might be different, and I'm not sure if the MCP is correctly configured. Regarding the OpenCode API, I need to check if we've used the query for the directory. The GUI could potentially pass the workspace as a directory. I need to determine the current workspace, which might just be the root. It seems like the global config should merge, but I'm curious if the OpenCode config is project-specific, especially concerning the query. Let's look into querying with the root directory.
**Configuring mcp-remote settings** I see that the mcp-remote is available. I should edit the local configuration to see if that resolves the 429 issue, although I'm not sure if it actually will. I might want to test opencode with /mcp after restarting. Plus, it could be helpful to set the no duplicate option as well. I'll need to apply that patch. It's a bit of a puzzle, but let's figure it out!
**Troubleshooting npm commands** I'm considering using npm view or npx mcp-remote with a URL and help option to get more information. It seems like checking the package README might also be helpful, using something like webfetch or npm view. However, I'm running into connection issues because the mcp-remote process is closing when there's a 429 error. I might need to run things manually to dig into the logs. It's definitely a bit tricky!
**Testing configuration options** I think I need to use "npx add-mcp --transport http" because it might correctly write the config remote. The opencode schema doesn’t distinguish, but maybe add-mcp includes a URL with a trailing /mcp? Let's test this in /tmp. It only writes /opencode.json, but I might try adding the --transport http and --agent opencode. However, the opencode schema might not support HTTP. I need to ensure the final message indicates that upstream 429 cannot be fixed.
**Creating a patch file** I need to create a file called apply_patch, and I'll be using the SDK API for that. First, I want to take a careful look at the files to ensure I know exactly what I’m working with. It’s important to have a clear understanding before I dive in. I’ll proceed step by step to make sure I don’t miss anything crucial while working on this task!
**Setting up environment** I need to open the code environment at the current working directory, allowing Node to resolve imports from the script directory. Using ESM resolution from the root path to the Node modules seems fine. It’s important to mention that this isn’t an official remote but could use the same server name. I might call this configuration "gemini-api-docs-mcp." Next, I’ll set up the `search_documentation` tool and get started!
**Troubleshooting script issues** I think I need to consider using chmod or bash, but maybe that's not necessary with Node. I'm wondering if I should test the script using an inspector and whether I need to use the MCP client. Restarting and querying /mcp sounds like a plan. Also, there might be a potential error in the Node syntax because of how regex is set up in the score. I feel like I need to review the regex character class to ensure it’s correct. Let’s look into that.
**Clarifying final steps** I need to be concise about the final outcomes. I should mention the official remote connection with a 429 status and that there's a fallback to a local connection. The user asked me to continue, so I should include the next steps or update any todos. I want to ensure that I properly inform the user about what's happening and what actions they might need to take next!
**Evaluating script removal** I need to remove the MCP block and delete the script. It's possible that the package files were preexisting, so I should check the package.json to confirm this. Understanding what’s involved with the packages will help me figure out what steps to take next. It feels like I might be juggling a few things here, but making sure I backtrack a bit first seems important to avoid any mistakes!
**Considering package management** I think I need to remove the existing dependency and run npm install. I'll apply the patch to the package while also removing the script and the MCP block. After making those edits, it seems like updating the package-lock with npm install might be necessary. I could also use npm uninstall for @modelcontextprotocol/sdk since it modifies files automatically. But I'll need to do this after the patch. Unused dependencies in node_modules can be cleaned up too.