# Connect the guides-ai MCP Server to Your Agent

> Add the guides-ai MCP server to Claude Code, Cursor, or any agent with one URL. No install, no token. Then search the whole guide library from chat.

- Canonical: https://guides-ai.com/guides/connect-guides-ai-mcp-server/
- Plate 05.09 · Topic: MCP (https://guides-ai.com/topics/mcp/)
- Published: 01 Nov 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

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:

```text
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

```bash
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):

```json
{
  "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:

```text
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

```bash
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](/guides/claude-code-remote-mcp-servers/), [add an MCP server to Cursor](/guides/cursor-mcp-servers/), or [troubleshoot a server that won't connect](/guides/claude-code-mcp-troubleshooting/).