Skip to content

Add a getting-started path for site owners, on the plugin page and in the site #369

Open
Open
Add a getting-started path for site owners, on the plugin page and in the site#369

Description

@miriamschwab
miriamschwab
opened on Oct 4, 2026

Thanks for getting MCP Adapter into the plugin directory. A lot of people are now finding it and I think many of them are site owners who want to connect Claude, Cursor, or ChatGPT to their own site.

However, these users are probably getting stuck right after activation. The installation steps on the plugin page end at "register abilities or install a plugin that does so," and the Getting Started guide on GitHub is written for developers: registering abilities in PHP, creating custom servers, and testing with WP-CLI. Neither one tells a site owner how to connect a client, how to authenticate, or what to expect once they're connected. There's also nowhere obvious in wp-admin for them to see which abilities are active on the site. If a client connects and finds nothing to work with, nothing on the site explains why.

I know there's no admin UI on purpose right now, so here are some ideas to help end users get up and running with the MCP Adapter without needing one.

On the WordPress.org plugin page

  • Split Installation into two paths: "Connect an AI client to my site" and "Expose my plugin's abilities over MCP."
  • For the first path, add a short walkthrough: creating an Application Password under Users > Profile, connecting one or two common clients, and a first prompt to test the connection. When I connected a site using an AI agent, I gave it only the site address and it found the MCP endpoint in the REST API index. It would help if every client could do that, through a standard discovery method, so site owners never have to deal with the endpoint path at all.
  • Say plainly what's exposed out of the box. If nothing is, say that.
  • Add FAQ entries for the common failures: 401 errors, hosts that disable Application Passwords, and "connected, but no tools."
  • Add a screenshot or two of a client listing WordPress tools.

Docs

A site-owner guide on learn.wordpress.org or developer.wordpress.org would give the plugin page a stable link, and it would show up in search more often than the GitHub docs do.

In the site

  • A dismissible notice after activation that links to the above-mentioned guide.
  • A Site Health section that lists the abilities registered on the site, shows which are exposed over MCP and which aren't (and why), and confirms whether the adapter is active and Application Passwords are available. Including the endpoint URL there would also help when something breaks. Site Health already holds this kind of diagnostic information, so it can fit there without adding a new menu item.
  • A "Getting started" link in the plugin's row on the Plugins screen, pointing to the Site Health section if that exists, or to the above-mentioned site-owner guide.

I'm happy to draft the plugin page copy or the site-owner guide if that would help get one of these moving.

Activity

  1. github-project-automation
    added this to WordPress MCP Adapter Planningon Oct 4, 2026

  2. galatanovidiu commented on Oct 5, 2026

    @galatanovidiu
    galatanovidiu
    on Oct 5, 2026
    Contributor

    Thanks for writing this up, Miriam. These are good points, and I agree site owners get stuck right after activation today.

    I think we should split this into smaller issues and keep this one as the parent tracker. The items have different owners and different risk, and the docs work should not wait on the code decisions. Here is the split I have in mind:

    1. Plugin page copy (readme.txt). The two installation paths, the Application Password walkthrough, what is exposed by default, FAQ entries for 401 errors, disabled Application Passwords and "connected, but no tools", plus screenshots. This is docs only, so it is the fastest one to ship.
    2. Site-owner guide on learn.wordpress.org or developer.wordpress.org. This goes through a separate process. Until it exists, a page in docs/getting-started/ can be the link target.
    3. Site Health section. Registered abilities, which ones are exposed over MCP and why, adapter status, Application Password availability and the endpoint URL. This is the biggest code change. We have no admin UI on purpose, so the maintainers need to agree on this one first.
    4. Activation notice and a "Getting started" link on the Plugins screen. Small change, but it needs 2 or 3 as the link target, so it comes last.
    5. Standard endpoint discovery for clients. This is more an ecosystem and spec question than an adapter task, so it needs research first. It may be related to Your account was authorized, but no MCP server was found at the provided URL #361.

    You offered to draft the plugin page copy. That would help a lot, and it maps directly to item 1. If this split works for you, I will open the sub-issues and link them here.

    cc @justlevine @gziolo @jeffpaul, what do you think about the split, and especially about item 3?

  3. bacoords commented on Oct 5, 2026

    @bacoords
    bacoords
    on Oct 5, 2026
    Contributor

    Thanks for raising this. This was an issue we had at Woo where there's no user-facing documentation we could point to for setting up MCP, only technical integration instruction.

    Location is a tough one to consider, because the MCP Adaptor itself is not in core, so it probably don't make sense in wordpress.org/documentation just yet. A plugin readme is definitely helpful, but the adaptor does still exist as a package and I could imagine some plugins continuing to distribute it that way as well so that installing a separate plugin isn't required for users.

    Currently, developer.wordpress.org has no documentation on the MCP Adaptor at all, (though it does cover the Abilities API), and that seems like a logical destination. WP-CLI is not technically "in core" but has documentation on the developer site. I'd be happy to help push through some MCP-specific documentation on the developer site, mostly based on the existing docs in the repo, but also including these user-focused setup instructions mentioned.

    Regarding admin UI for managing abilities: There's a similar issue open in the AI experiments plugin WordPress/ai#992 and I think it's worth having alignment on where all UI, features, and documentation for MCP lives going forward. For example, at Woo we have explorations of admin UI to manage our abilities, but I could imagine having this all in a core or MCP Adaptor as a better alternative.

    Personally, I'd prefer if we stopped using AI Experiments as a home for anything relating to MCP, and narrow the focus and surface area of where MCP-specific features and documentation exists.

  4. justlevine commented on Oct 5, 2026

    @justlevine
    justlevine
    on Oct 5, 2026
    Contributor

    Personally, I'd prefer if we stopped using AI Experiments as a home for anything relating to MCP, and narrow the focus and surface area of where MCP-specific features and documentation exists.

    +1

    Regarding admin UI for managing abilities:

    If you replace "abilities" with MCP tools, it makes it a lot easier to make this plugin the natural home for some form of management. The fact that most of the Abilities in the AI plugin are so MCP-pilled that they don't really make sense in Core isn't just what's prevented them from being shipped to core, but IMO makes relocating them here much more justifiable, and takes the pressure off of shipping Abilities to core just so MCP consumers have access to them.

    In fact, in addition to a generic Site Health tab for available Abilities, a Tools > MCP Adapter screen seems like a good place to show an integration snippet, link to docs, and show the available servers + and what each has available. Management (as justified) could evolve there naturally as well.

  5. webmyc commented on Oct 5, 2026

    @webmyc
    webmyc
    on Oct 5, 2026
    Contributor

    Thanks @miriamschwab for writing this up, and @galatanovidiu for the split. Two of the five are problems I have already hit while building Respira, a commercial WordPress MCP plugin, so I can help there.

    5. Endpoint discovery. The two things that tripped up Claude for me: it only starts the OAuth flow after a 401 with a WWW-Authenticate header that points at the resource metadata, and Claude Desktop probes the URL before it ever shows the sign-in screen, so that probe has to get the same answer. When either is missing you get exactly the "authorized, but no MCP server was found" message from #361. I'm happy to write up what each client expects, as input for the research.

    3. Site Health. The free plugin I maintain, Inhale (MCP Abilities), is a settings screen for exactly this: it lists the abilities registered on a site and lets the owner choose which are exposed over MCP. If the maintainers agree to a Site Health section, I can contribute that logic as a PR, scoped however you decide.

  6. gziolo commented on Oct 6, 2026

    @gziolo
    gziolo
    on Oct 6, 2026
    Member

    Thanks for the detailed proposal. Improving the plugin page and adding a site-owner guide make sense, and they can move forward independently of any UI decisions. Since you offered, a draft of the plugin page copy or the guide would be a great place to start.

    On the Site Health section proposed in @galatanovidiu's breakdown, I'd support exploring it as read-only diagnostics: available servers, their endpoints, abilities exposed over MCP, and whether Application Passwords are available. Controls for managing what's exposed are a different question and need their own discussion. A "Getting started" link in the plugin row pointing to the guide seems like a low-cost addition as well.

    A dedicated management screen and moving MCP-oriented abilities into this plugin go beyond onboarding. Could we open separate issues for those, so this one can stay focused on documentation and diagnostics?

  7. webmyc commented on Oct 7, 2026

    @webmyc
    webmyc
    on Oct 7, 2026
    Contributor

    I opened #375 with a draft of the site-owner guide (item 2), as a page in docs/getting-started/, so the plugin page and a later "Getting started" link have something to point to. Corrections welcome, especially from anyone who's tried it on a fresh site.

    @miriamschwab the plugin page copy is yours, so I left readme.txt alone. In case it saves you time, here is FAQ wording for the failures I see most in support. Use any of it, or none.

    FAQ wording 
    == Frequently Asked Questions ==

= What can an assistant do on my site out of the box? =

MCP Adapter gives clients three tools: list the public abilities on your site, read one ability's details, and run it. Which abilities exist depends on WordPress and on your plugins. If no plugin has made an ability public, the list is empty and the assistant has nothing to do yet.

= My client gets a 401 error =

The site did not accept the username and Application Password. Check both, and check that the password has not been revoked under Users > Profile. If they are right, your server may be removing the Authorization header; ask your host to pass it to PHP.

= I cannot find Application Passwords under Users > Profile =

WordPress only shows them on sites served over HTTPS. Some security plugins and hosts also turn them off.

= Can I connect claude.ai or ChatGPT in the browser? =

Not directly. Their connectors sign in with OAuth, which WordPress and MCP Adapter do not provide. Use a desktop client, or a plugin that adds an OAuth sign-in.

  8. saarnilauri commented on Oct 8, 2026

    @saarnilauri
    saarnilauri
    on Oct 8, 2026
    Contributor

    I have drafted an article to make.wordpress.org/ai on how to connect the agent to the site using MCP Adapter.

    Here is the Slack thread related to it

  9. webmyc commented on Oct 8, 2026

    @webmyc
    webmyc
    on Oct 8, 2026
    Contributor

    @saarnilauri nice, glad there will be a make/ai post. The site-owner guide in #375 is approved, so it might be worth linking the two and keeping them consistent. Three things that tripped people up while I wrote it, in case they help the article:

    • Endpoint from the Site Address. Building it from the domain breaks installs in a subdirectory; Settings > General > Site Address plus /wp-json/mcp/mcp-adapter-default-server works everywhere (and /?rest_route= with plain permalinks).
    • base64 for a Basic header. GNU base64 wraps long output, so the header breaks for long usernames; | tr -d '\n' keeps it on one line.
    • claude.ai and ChatGPT in the browser connect through OAuth and have nowhere to put an Application Password, so they can't reach the adapter on its own today. Saying that early saves readers a frustrating hour.

    Some hosts also strip the Authorization header on /wp-json/ (#315 has the probes). Happy to review the draft if you share it.

  10. saarnilauri commented on Oct 8, 2026

    @saarnilauri
    saarnilauri
    on Oct 8, 2026
    Contributor

    @webmyc checked #375 and what the site-owner guide contains and revised my draft. Here is the public preview link: https://make.wordpress.org/ai/?p=1413&preview=1&_ppp=03af94ba5b

  11. webmyc commented on Oct 8, 2026

    @webmyc
    webmyc
    on Oct 8, 2026
    Contributor

    @saarnilauri this reads really well, thanks for folding the guide in. Three small suggestions, all optional:

    • Endpoint for subdirectory installs: a note that the URL is the Site Address (Settings > General) plus /wp-json/mcp/mcp-adapter-default-server, so https://example.com/blog becomes https://example.com/blog/wp-json/..., and that plain permalinks need /?rest_route=/mcp/mcp-adapter-default-server.
    • A short troubleshooting section: a 401 usually means the username or application password is wrong, or the host strips the Authorization header before WordPress sees it (Connect flow: detect which endpoint form works on the host instead of printing one #315 has the probes); rest_no_route usually means the plugin is inactive or plain permalinks are on. The site-owner guide from Docs: add a site-owner guide for connecting an AI client #375 covers these if you'd rather link to it.
    • Site Health: if Add a read-only MCP Adapter section to Site Health #376 lands, Tools > Site Health > Info shows the exact endpoint, the exposed abilities and whether application passwords work, which is the first place to look when the "simple question" test returns nothing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions