GoBuildWP CloudConnect your sites through one workspace.Explore Cloud →
GoBuildWP
Download freeDownload

Editor with agent mode, Native OAuth

VS Code WordPress MCP. The servers key, and a trust prompt.

VS Code WordPress MCP configuration differs from almost every other client in one word: .vscode/mcp.json nests servers under servers, not mcpServers. VS Code runs the OAuth sign-in itself, asks you to trust a server before its first start, and shows each server's output in its own channel.

Get GoBuildWP free Setup steps

Checked against VS Code's documentation on 29 September 2026, entries from GoBuildWP Free 1.18.6

By GoBuildWPContent updated How we check claims

.vscode/mcp.jsonOAuth 2.1
{
  "servers": {
    "gobuildwp-your-site-com": {
      "type": "http",
      "url": "https://your-site.com/wp-json/mcp/wppilot-oauth"
    }
  }
}
Workspace file
.vscode/mcp.json (key: servers)
Portable file
.mcp.json (key: mcpServers), which VS Code now prefers for new servers
User file
MCP: Open User Configuration
Diagnose
MCP: List Servers, Show Output

Connect screen

What the Connect screen writes for VS Code

Remote VS Code OAuth and token entries use the servers wrapper, type http and url, with headers for token authentication. The Application Password bridge instead uses command, args and env for stdio. The protected token example below prompts for the secret instead of saving a literal token. Use the generated site URL; leave OAuth project entries secret-free. VS Code tries Streamable HTTP first and falls back to SSE; GoBuildWP answers the first. The same shape works in a workspace file or in your user configuration.

OAuth 2.1type http and url. VS Code 1.101 added MCP authorization and 1.106 added Client ID Metadata Documents, which it prefers when a server supports them, as GoBuildWP does.
Access tokenheaders with Authorization. Swap the literal for ${input:wppilot-token} and a promptString input with password: true so VS Code asks once and stores it.
Application PasswordThe npx bridge under servers. Needs Node.js; OAuth needs nothing extra.

Endpoints on your site: /wp-json/mcp/wppilot-oauth for OAuth, /wp-json/mcp/wppilot for tokens and passwords. Through the optional GoBuildWP Cloud instead, every client uses https://app.gobuildwp.com/mcp with the server name gobuildwp, and a personal Cloud token is read from GOBUILDWP_TOKEN where the client supports environment variables.

.vscode/mcp.jsonAccess token
{
  "servers": {
    "gobuildwp-your-site-com": {
      "type": "http",
      "url": "https://your-site.com/wp-json/mcp/wppilot",
      "headers": {
        "Authorization": "Bearer ${input:wppilot-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "wppilot-token",
      "type": "promptString",
      "description": "GoBuildWP access token",
      "password": true
    }
  ]
}

Setup

Configure VS Code for a WordPress site

Workspace configuration travels with the repository; user configuration follows you. Pick based on who else should get the server.

  1. Open the right file

    For one project, create .vscode/mcp.json. For every workspace, run MCP: Open User Configuration from the Command Palette. MCP: Add Server walks through the same choice interactively.

  2. Paste the generated block

    Merge it into the existing servers object if the file already has one. The name GoBuildWP suggests is what the tools will be grouped under in chat.

  3. Trust the server

    The first start of a server outside a trusted workspace shows a trust dialog, and it comes back after any change to the entry. Workspace servers follow Workspace Trust.

  4. Sign in

    VS Code opens your WordPress login. The grant is listed in the Accounts menu, where you can sign out; Authentication: Remove Dynamic Authentication Providers clears the registered client entirely.

  5. Pick tools in chat

    Open agent mode, press Configure Tools and tick only the WordPress abilities the task needs. It keeps you well under the per-request tool cap.

Verify the connection before allowing changes

Select Read Only explicitly; the default is Production Safe. Use a dedicated identity with manage_options on a single site, or superadmin on multisite. Match the named tool call, site URL and returned record ID against WordPress.

First connection checkRead Only
Use the gobuildwp-your-site-com MCP server in VS Code. Do not change anything.

1. Report the active GoBuildWP safety profile.
2. List the abilities this connection can see.
3. Call wppilot/get-site-settings and report the site URL and locale.
4. Call wppilot/list-content for the five newest pages,
   then wppilot/get-content on one of them.
5. Name every ability you called and each WordPress ID you read.

These setup instructions are not a recorded live-client test. Keep credentials out of repositories, logs and shared files.

Inside VS Code

The Command Palette is the control panel

MCP: List Servers shows every configured server; selecting one offers start, stop, restart and Show Output. The output channel logs the connection, the sign-in and each failed request with its HTTP status, which is where a stripped Authorization header or a 403 from a security plugin becomes visible.

If a server fails, the Chat view shows an error indicator that jumps to the same output. After you change what GoBuildWP exposes, MCP: Reset Cached Tools makes VS Code fetch the list again; MCP: Reset Trust forgets the trust decisions if you want to be asked again.

A single chat request can carry at most 128 tools. A site with many Pro modules enabled can approach that alongside other servers; deselect abilities in Configure Tools, or disable modules on the site you are not using, rather than raising limits.

Signs it worked

  • MCP: List Servers shows the server running
  • Show Output has no 401 or 403 lines
  • Configure Tools lists the wppilot/ abilities
  • Tool calls ask for approval until you allow them

Troubleshooting

VS Code errors and their causes

SymptomCause and fix
The file is ignored completelyThe block uses mcpServers. .vscode/mcp.json expects servers. The portable mcpServers form belongs in a workspace .mcp.json instead.
The server never starts and no sign-in appearsThe trust dialog was dismissed. Run MCP: List Servers, start the server, and accept the trust prompt.
Cannot have more than 128 tools per requestVS Code's cap. Deselect tools in Configure Tools, or reduce the WordPress abilities you expose on the site.
OAuth fails on an older buildMCP authorization arrived in VS Code 1.101. Update, or use a token with an input variable.
Old tools still appear after changing the siteThe tool list is cached. Run MCP: Reset Cached Tools, or restart the server from MCP: List Servers.

First task

A first agent-mode request

Agent mode in VS Code works best with a concrete, bounded job. This one inventories the block editor content of one page and changes nothing.

VS Code promptReads only
Use only the WordPress MCP tools. Read only.

1. wppilot/search-content for "about" and pick the
   About page.
2. wppilot/gutenberg-get-content on it: list the
   blocks in order.
3. wppilot/list-revisions: how many revisions, and
   when was it last edited?
4. Suggest one structural improvement.

Related

Guides that share VS Code's format

  • GitHub Copilot: the same servers shape, plus the Copilot CLI and cloud agent
  • Cline: an agent extension with its own MCP settings file
  • Cursor: a VS Code-based editor that uses mcpServers
  • Amazon Q: AWS's plugin for VS Code, with its own default.json
Every client guide (26)

VS Code documentation read on 29 September 2026

Agent mode on a block editor site

How VS Code agent mode edits block content safely

Block editor pages are where VS Code's agent mode most often goes wrong, because core and third-party blocks are saved by the editor's own JavaScript. GoBuildWP does not fake that serialisation on the server. Instead, agent mode queues a change with wppilot/gutenberg-add-pending-change, marks the batch ready with wppilot/gutenberg-enable-batch-finalization, and the change is finished by a Block Editor Queue page open in wp-admin, which runs the real editor code. Until that page completes the batch, nothing on the post is live.

In practice that means keeping a wp-admin tab open on the staging site while the agent works, and asking it to report the batch status rather than announce success. wppilot/gutenberg-get-finalization-url returns the queue page's address and whether a finaliser is online, which explains most "it said it saved but nothing changed" reports.

Leave notes for an editor instead of editing

Not every review should end in a write. On WordPress 7.1 and later, wppilot/add-block-note attaches a Note to one block, shown in the editor's Notes sidebar with the author marked as an AI agent, so a person decides whether to act on it. wppilot/list-block-notes reads existing threads and their status, and reply and resolve abilities exist for the follow-up. Adding a note does create a revision, because the note ID is stored on the block, but the block's own content is untouched.

This suits a VS Code workflow where the developer owns the code and someone else owns the words: the agent reviews a page against the brief in the repository and leaves its suggestions where the content owner already works.

  • "Read the About page with wppilot/gutenberg-get-content, compare it with docs/brief.md, and leave a block note on any paragraph that contradicts the brief. Do not change the text."

Direct entry or GoBuildWP Cloud in mcp.json

A direct servers entry per site keeps nothing between VS Code and WordPress and suits a repository tied to one site. GoBuildWP Cloud lists VS Code Copilot among its OAuth apps, so one servers entry pointing at the Cloud link, in your user configuration, can reach every site you allow. The tool cap still applies per request, which is one more reason to tick only the abilities a task needs.

FAQ

VS Code questions

Why does VS Code use servers instead of mcpServers?

servers is VS Code's own format for .vscode/mcp.json and user configuration, and it is what GoBuildWP's Connect screen generates. VS Code also reads the portable mcpServers form from a workspace .mcp.json or the Copilot global file, ~/.copilot/mcp-config.json. When GoBuildWP Cloud's setup was checked on 9 October 2026, VS Code's documentation was steering new setups toward that portable form and describing .vscode/mcp.json as the older location, which is why Cloud's VS Code steps use it. Both work on current releases as long as each shape sits in its matching file; which one a given VS Code version prefers has not been tested here.

Do I need GitHub Copilot to use a WordPress MCP server in VS Code?

Agent mode and MCP tools are part of VS Code's chat, which is powered by Copilot. The GitHub Copilot guide covers the Copilot-specific surfaces: the CLI, Visual Studio and the cloud agent.

Can a dev container use the WordPress server?

Yes. VS Code reads MCP servers from customizations.vscode.mcp.servers in devcontainer.json, so a container image can ship the entry.

Where are WordPress credentials stored?

OAuth grants are held by VS Code's authentication system and shown in the Accounts menu. Values from input variables are stored by VS Code after the first prompt, not in the file.

Put WordPress in VS Code's agent mode.

One servers entry, one trust prompt, one sign-in, and only the tools the task needs ticked.

Get GoBuildWP free See Pro pricing