Connect the guides-ai MCP Server to Your Agent

guides-ai runs its own MCP server. Point any MCP-capable agent at one URL and it can search every guide here and pull a guide’s full text straight into context — so the agent answers from the current guide instead of stale training memory. There’s nothing to install, no API key, and no sign-in.

The endpoint:

https://guides-ai.com/mcp

It speaks MCP over streamable HTTP and exposes four tools: search_guides, get_guide, list_guides, and list_topics.

1. Add it to Claude Code

claude mcp add --transport http guides-ai https://guides-ai.com/mcp

What it does: registers a remote streamable-HTTP server named guides-ai. The --transport http flag is required for a URL — without it Claude Code treats the argument as a local stdio command. There’s no header to pass, because the server is public and read-only. Add --scope user to make it available in every project.

2. Add it to Cursor, or any mcpServers client

Cursor, Windsurf and most other clients read the same mcpServers shape. Put this in ~/.cursor/mcp.json (global) or .cursor/mcp.json (checked into one repo):

{
  "mcpServers": {
    "guides-ai": {
      "url": "https://guides-ai.com/mcp"
    }
  }
}

What it does: connects over HTTP. There’s no headers block because there’s no auth. Codex CLI, Gemini CLI and Claude Desktop accept the same URL in their own config files — see the end of this guide for each.

3. Use it from chat

Name the server (or a tool) in your prompt so the agent actually calls it instead of guessing:

Use the guides-ai MCP server to find how to run Ollama in Docker with a GPU, then follow the exact steps.

What it does: search_guides returns the top matches with their slugs; the agent then calls get_guide on the one it wants to read that guide’s Markdown into context and work from it. list_topics and list_guides browse the catalogue when you’d rather see the map first.

4. Verify the connection

claude mcp list

What it does: prints every configured server and whether it connected — a working one shows ✓. Then ask for a guide by topic in a session so you see search_guides actually fire.

Verify it worked

• ✗ failed to connect — the URL must be exactly https://guides-ai.com/mcp, with no trailing slash and not the bare site root. Re-check what was saved with claude mcp get guides-ai.
• command not found when adding it — you left off --transport http, so Claude Code tried to run the URL as a local program. Remove it with claude mcp remove guides-ai and add it again with the flag.
• The agent answers from memory and never calls a tool — ask it explicitly: “use the guides-ai server to search for …”. Clients skip a tool when they think they already know the answer, so a green status dot isn’t proof; a real tool call is.

---

Next: connect any remote MCP server over HTTP, add an MCP server to Cursor, or troubleshoot a server that won’t connect.