Verification & troubleshooting

Confirm it really works

A successful setup command only means the client stored the address. After restarting the client or opening a new session, have the agent call list_docs or search_docs once and confirm that pages or results come back.

Clients only load a new MCP configuration when they restart or open a new session.

Tool calls need approval

When Codex reports that a tool call needs approval, approve it in an interactive session.

A session that never asks for approval blocks remote MCP tool calls. Once you have confirmed that only the three read-only tools are needed, restrict and approve them in ~/.codex/config.toml:

[mcp_servers.qnbot_docs]
url = "https://docs.qnbot.com/mcp"
enabled_tools = ["search_docs", "get_doc", "list_docs"]

[mcp_servers.qnbot_docs.tools.search_docs]
approval_mode = "approve"

[mcp_servers.qnbot_docs.tools.get_doc]
approval_mode = "approve"

[mcp_servers.qnbot_docs.tools.list_docs]
approval_mode = "approve"

If you already added a [mcp_servers.qnbot_docs] block, replace it with the complete configuration above instead of keeping two blocks with the same name in config.toml.

Connection failures and unavailable service

Check that the network the client runs on can reach https://docs.qnbot.com/mcp.

Opening /mcp in a browser can return the error below. That is expected: MCP clients use protocol requests, so an ordinary web GET cannot tell you whether the service is down.

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Method not allowed."
  },
  "id": null
}

Order of checks

1. Confirm the client has been restarted and the server appears in its MCP list.
2. Have the agent call list_docs: returned pages mean the connection works, and a permissions problem usually sits in tool approval.
3. When a call returns pages but no content, have the agent call get_doc with the returned markdownPath, as described in Available tools.