MCP Server: CLI Tools Connection Instructions

Common Requirements

• A supported CLI: Claude Code, OpenAI Codex, or Gemini CLI
• Each CLI's own authentication (vendor account or API key)
• Your GovSpend API key
• MCP endpoint: https://mcp-spark-prod.govspend.com/mcp

Claude Code

Add the server

Run this from any terminal:

claude mcp add --transport http govspend https://mcp-spark-prod.govspend.com/mcp 

That's it. Claude Code stores the server in its config and handles OAuth on first use.

Headless / CI use

To skip the interactive OAuth flow, pass the API key as a header at registration time:

claude mcp add --transport http govspend https://mcp-spark-prod.govspend.com/mcp \   --header "Authorization: Bearer your-api-key-here" 

OpenAI Codex CLI

Option A — CLI command

codex mcp add govspend --url https://mcp-spark-prod.govspend.com/mcp 

Then trigger the OAuth flow:

codex mcp login govspend 

Option B — Manual config

Edit ~/.codex/config.toml:

[mcp_servers.govspend] url = "https://mcp-spark-prod.govspend.com/mcp" 

For headless or CI use, pass the key via header instead of OAuth:

[mcp_servers.govspend] url = "https://mcp-spark-prod.govspend.com/mcp" http_headers = { "Authorization" = "Bearer your-api-key-here" } 

Do not include experimental_use_rmcp_client = true. That flag was removed from Codex on December 20, 2025 — remote MCP is now the default. Older guides still reference it; those guides are outdated.

Gemini CLI

Consumer-tier note: Free, Google AI Pro, and Ultra consumer tiers stopped serving Gemini CLI on June 18, 2026 — Google is migrating those users to Antigravity CLI. Paid Gemini API keys and Code Assist Standard/Enterprise continue to work as before.

Option A — CLI command

gemini mcp add --transport http govspend https://mcp-spark-prod.govspend.com/mcp 

This writes to ~/.gemini/settings.json by default. Use --scope project to write to .gemini/settings.json in the current directory instead.

Option B — Manual config

Edit ~/.gemini/settings.json:

{   "mcpServers": {     "govspend": {       "url": "https://mcp-spark-prod.govspend.com/mcp"     }   } } 

Use url, not httpUrl. The httpUrl field and the npx mcp-remote shim were both retired in late 2025 — a single url field with auto-detection replaced them.

Verifying the Connection (Any CLI)

Step 1: Launch your CLI (claude, codex, or gemini) from a terminal.

Step 2: Inside the session, type:

/mcp 

govspend should appear in the list. It may show as "not connected" until the first tool call — this is expected for OAuth servers.

Step 3: Trigger OAuth with a real question:

What are the top 10 vendors selling cybersecurity services to Texas state agencies in the last 12 months?

Your browser opens, you sign in with your GovSpend API key, and the token is cached for future sessions.

Troubleshooting

Before anything else, confirm the server is up: curl https://mcp-spark-prod.govspend.com/health

/mcp shows govspend as "not connected"

• Trigger a real GovSpend question first — HTTP MCP servers don't connect until the first call.
• Re-check the URL: no trailing slash, no http://, must include /mcp.
• Run with your CLI's debug flag (--debug on Gemini, etc.) for verbose logs.

OAuth window doesn't open or hangs

• Pop-up blockers, sandboxed terminals, or remote SSH sessions can block the browser launch.
• Manually open the URL your CLI prints if auto-launch fails.
• Verify your GovSpend API key is valid and your subscription includes MCP access.

Token expired or auth keeps re-prompting Delete the CLI's stored token and re-authenticate:

• Claude Code: claude mcp logout govspend
• Codex: codex mcp logout govspend
• Gemini: rm ~/.gemini/mcp-oauth-tokens.json

Tools call but return empty results

• The MCP respects your GovSpend entitlements — confirm your account has access to the data you're requesting.
• Try narrowing your query. Broad questions sometimes return empty when more specific ones succeed.

Need to remove or re-add the server

Then re-run the add command for your CLI.