Use RoamSEO with ChatGPT
Install the RoamSEO plugin in ChatGPT, or add a custom connection, and check that it works.
Install the RoamSEO plugin for ChatGPT to use RoamSEO on chatgpt.com and in the ChatGPT desktop app. It adds the RoamSEO tools and SEO skills, and you sign in with your RoamSEO account.
If you paste the setup prompt into a regular ChatGPT chat, it sends you to the plugin. ChatGPT cannot install it by itself.
Choose your setup path
| Where you want to work | How to connect |
|---|---|
| ChatGPT on the web or in the desktop app | Install the RoamSEO plugin |
| Plugin unavailable | Add a custom connection |
| Codex in the ChatGPT desktop app | Paste the agent setup prompt in Codex |
RoamSEO billing is separate from your ChatGPT subscription. See OpenAI's plan support for Codex access.
Install the RoamSEO plugin
- Open the RoamSEO plugin in ChatGPT.
- Select Install plugin, then sign in to RoamSEO in the window that opens and approve the connection. No account yet? Create one from that sign-in page.
- Start a new chat. Type
@and select RoamSEO, or open the + menu and choose RoamSEO. - Send the connection check below.
You do not need a RoamSEO API key. The plugin connects to hosted RoamSEO.
Custom connection
Use a custom connection if the plugin isn't available for your account. It works on ChatGPT Free and paid plans. It gives ChatGPT the RoamSEO tools but not the SEO skills. To use it in the ChatGPT desktop app, add it on chatgpt.com first.
-
Sign in to chatgpt.com.
-
If your version shows it, open Settings → Security and login and enable Developer mode. Some versions expose the custom connection flow directly in Plugins.
-
Open Plugins, select +, then Create MCP App. In versions with the older interface, look for Settings → Apps → Advanced settings → Developer mode, then Create or Add custom app.
-
Enter these details:
Field Value Name RoamSEOServer URL https://app.roamseo.com/mcpAuthentication OAuthType the full URL, including
https://. -
Review the custom connection notice and create the connection. Sign in to RoamSEO in the window that opens and approve the connection. Return to ChatGPT. If the new plugin needs installation, open it under Personal and select Install or +.
-
Start a new chat. Open the + / tools menu and select RoamSEO. In versions that show Developer mode in that menu, choose it and enable RoamSEO there. If the composer offers plugin mentions, you can also type
@and select RoamSEO. -
Send the connection-check request below.
Use OAuth for this flow. You do not need to create a RoamSEO API key or paste one into ChatGPT. Without the skills, you can still ask for keyword research, audits, or competitor research in plain language.
See OpenAI's connection guide for its current interface.
Codex in the desktop app
If you already use Codex in the desktop app, start a new Codex chat, then copy the agent setup prompt into that chat. Codex can configure its own connection and guide you through sign-in. Approve the RoamSEO login when prompted.
If you prefer manual setup, follow the Codex plugin guide, or add the MCP connection alone. Start a new Codex chat after installation if needed, then run the connection check below.
Codex and ChatGPT chats use separate connections. Run the connection check in the chat where you want to use RoamSEO. For the current mode controls, see OpenAI's desktop guide.
Check that RoamSEO is connected
Send this in a new chat with RoamSEO selected:
Use RoamSEO to check my connection and list my projects. Do not run SEO research or create anything.ChatGPT should call RoamSEO and return your connection status and project list. An empty project list is a successful connection check too. These reads use no RoamSEO credits.
If it says it cannot access RoamSEO, or only describes how to connect, setup is still incomplete. Check that RoamSEO is installed, signed in, and selected in this chat. Start a new chat after changing the connection.
Once the check succeeds, try:
Use RoamSEO to help me choose one SEO task for my website. Ask about my goal before starting paid research.The RoamSEO plugin also includes SEO skills, such as SEO Audit. The @ menu shows RoamSEO itself, not its skills. Select RoamSEO and ask for a workflow by name, for example: "Use the RoamSEO SEO Audit skill on example.com."
Troubleshooting
| What you see | What to do |
|---|---|
| The RoamSEO plugin isn't available | Availability depends on your ChatGPT plan, workspace, and region. On a workspace plan, ask your admin to allow it. Otherwise, add a custom connection. |
| No Developer mode or Create MCP App option | Check Settings → Security and login and Settings → Plugins → Developer mode. On a workspace plan, ask your admin whether custom connections are allowed. |
| "Error fetching OAuth configuration: Unsafe URL" | Enter the server URL in full as https://app.roamseo.com/mcp, with no spaces. A URL without https:// is rejected. |
| ChatGPT asks for a client ID or secret | Keep OAuth selected and wait for discovery. Open Advanced OAuth settings and use Dynamic Client Registration (DCR) if offered. You should not need to supply your own client credentials for hosted RoamSEO. |
| The login window never appears | Allow the sign-in window to open, then retry authentication from the RoamSEO connection's details. |
| Login succeeds but tools are unavailable | Finish installing the plugin if prompted, start a new chat, and select RoamSEO from the tools menu. |
| ChatGPT gives general advice instead of calling RoamSEO | Select RoamSEO and resend the connection-check request. Check that ChatGPT calls a RoamSEO tool. |
| Codex works, but chatgpt.com cannot find RoamSEO | Connect ChatGPT web separately. It does not read your desktop Codex configuration. |
| You have no projects | An empty project list still confirms the connection. Create a project in RoamSEO when you are ready to start research. |
If setup still fails, contact contact@roamseo.com with your ChatGPT plan, web or desktop version, the step that failed, and the error message. Do not include passwords, API keys, or sign-in codes.
Update RoamSEO
For the RoamSEO plugin, start a new chat to load the latest tools. The plugin's skills update when RoamSEO publishes a new version of the plugin. Reconnect if ChatGPT reports that sign-in needs attention. Local Codex update commands do not update ChatGPT web.
For a custom MCP connection, open its details under Plugins, select Refresh to reload the tools, and start a new chat. Refresh updates tool definitions; it does not add repository skills. If sign-in has expired, authenticate again.
For Codex, use the agent update prompt or plugin commands in your Codex environment.