This guide walks you through setting up Claude Code with the Finix MCP server. After setup, you can ask Claude questions about Finix APIs and get accurate answers from our documentation.
Before you begin, make sure you have:
- Claude Code installed - Anthropic's CLI tool for AI-assisted development
- Internet connection - Required to reach
docs.finix.com
If you don't have Claude Code installed yet:
npm install -g @anthropic-ai/claude-codeOr with Homebrew on macOS:
brew install claude-codeFor detailed installation instructions, see Claude Code documentation.
Add the Finix MCP server with a single command:
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport httpClaude Code can now access Finix documentation.
Note: The MCP server's
searchtool returns results from both the API Reference and Guides. However, the detailed retrieval tools (get-endpoint-info,get-endpoints,get-full-spec-document) only work with the API Reference. To get the full content of a guide page, Claude can fetch the markdown version of any guide using the.mdURL pattern (see Enhancing Guide Access below).
The MCP server can search guides but doesn't have a dedicated tool to retrieve their full content. To give Claude full access to both API docs and guides, add the following to your project's CLAUDE.md file or system prompt:
## Finix Documentation Access
When answering questions about Finix:
1. Use the Finix MCP server tools (`search`, `get-endpoint-info`, `get-endpoints`) to find relevant API reference content.
2. For guide/tutorial content: after using the MCP `search` tool to find relevant guide pages, fetch the full content by appending `.md` to the guide URL. For example:
- `https://docs.finix.com/guides/getting-started/developer-quickstart.md`
- `https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms.md`
- `https://docs.finix.com/guides/payouts/adding-funds.md`
3. Always check both API Reference and Guides for a complete answer.This instruction tells Claude to combine the MCP server tools (for API reference) with direct markdown fetching (for guides), giving it full access to all Finix documentation.
After adding the MCP server, verify it's working:
claude mcp listYou should see finix-redocly-mcp in the list of configured servers.
Start a Claude Code session and ask a question about Finix:
claudeAPI Reference test:
Then try a test prompt:
"What authentication method does the Finix API use?"
If Claude responds with specific details about Finix API authentication (Basic Auth with API credentials), the connection is working.
Guide access test:
"How do I onboard a seller on Finix?"
If Claude responds with details from the seller onboarding guide (not just API endpoint info), guide access is working correctly.
To add the Finix MCP server only to a specific project, navigate to your project directory first:
cd /path/to/your/project
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http --scope projectThis creates a .claude/mcp.json file in your project, so the MCP server is only available when working in that directory.
To make the Finix MCP server available in all your projects (default behavior):
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http --scope userYou can also manually edit your Claude configuration file.
Location:
- macOS/Linux:
~/.claude.json - Windows:
%USERPROFILE%\.claude.json
Add the Finix MCP server to the mcpServers section:
{
"mcpServers": {
"finix-redocly-mcp": {
"type": "http",
"url": "https://docs.finix.com/mcp"
}
}
}After editing, restart Claude Code for changes to take effect.
Once configured, Claude automatically uses the MCP server when you ask Finix-related questions.
API Questions:
"What fields are required to create a Transfer?"
"How do I tokenize a card with Finix.js?"
"What's the difference between a Transfer and an Authorization?"
Integration Help:
"Show me an example of processing a refund"
"How do I set up webhooks for payment status updates?"
"What are the steps to onboard a seller?"
Troubleshooting:
"What does error code 402 mean?"
"Why would a Transfer be in PENDING state?"
"How do I handle declined payments?"
For the best results:
Be specific - "How do I create a card Authorization?" is better than "How do payments work?"
Reference API resources - Use terms like "Transfer", "Authorization", "Identity", "Merchant" when relevant
Ask for examples - "Show me an example of..." prompts Claude to pull code samples from documentation
Mention the environment - Specify "Sandbox" or "Production" if it matters for your question
If claude mcp list doesn't show finix-redocly-mcp:
Re-run the add command:
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport httpCheck your configuration file exists and is valid JSON
If Claude reports connection issues:
Check internet connection - Verify you can reach
docs.finix.comin a browserCheck for firewall/proxy issues - Corporate networks may block MCP connections
Try removing and re-adding:
Reset Connectionclaude mcp remove finix-redocly-mcp claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http
If Claude seems to be guessing instead of searching documentation:
Be explicit - Try "Search the Finix documentation for..." in your prompt
Check MCP is enabled - Run
claude mcp listto verify the server is configuredRestart Claude Code - Sometimes a fresh session helps
If Claude answers with only API endpoint details and misses relevant guide content:
- Add the
CLAUDE.mdinstructions - See the Enhancing Guide Access section above to instruct Claude to fetch guide markdown pages - Ask explicitly - Try "Check the Finix guides for how to..." to prompt Claude to search for guide content
The MCP server queries Finix's published documentation. If you notice outdated information:
- Check docs.finix.com directly to verify current documentation
- The MCP server reflects published docs, which are updated regularly
To disconnect Claude Code from Finix documentation:
claude mcp remove finix-redocly-mcp