Connect Claude to Finix MCP

Connect Claude to Finix MCP

This guide shows you how to use Claude Code with Finix MCP to ask questions about Finix APIs and get documentation-based answers.

Prerequisites

Before you begin, make sure you have:

Installing Claude Code

If you don't have Claude Code installed yet:

Install Claude Code

npm install -g @anthropic-ai/claude-code

Or with Homebrew on macOS:

Install with Homebrew

brew install claude-code

For detailed installation instructions, see Claude Code documentation.

Quick Setup

Run this command to add the Finix MCP server:

claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http

Claude Code can now access Finix documentation. The Finix MCP server's search tool finds results in both the API Reference and Guides. Detailed retrieval tools (get-endpoint-info, get-endpoints, get-full-spec-document) are only available in the API Reference. See Enhancing Guide Access to configure the agent for full access to the Finix documentation.

Enhancing Guide Access

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 Finix questions:

1. Use the Finix MCP server tools (like `search`, `get-endpoint-info`, `get-endpoints`) to find API details.
2. To access the full content of a guide or tutorial: after using the MCP `search` tool to identify relevant guide pages, copy the guide URL from the search result and add `.md` to the end of the URL before opening it. 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 lets Claude access Markdown guides and API references via MCP, ensuring full access to Finix docs.

Verify the Connection

After adding the MCP server, verify it works:

Check MCP Status

List MCP Servers

claude mcp list

You should see finix-redocly-mcp in the list of configured servers.

Test a Query

Run this command to start a Claude Code session:

Start Claude Code

claude

API Reference Test

Then try a test prompt:

"What authentication method does the Finix API use?"

If Claude responds with exact details about Finix API authentication, such as 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.

Configuration Options

Project-Level Configuration

Navigate to your project directory (e.g., cd /path/to/your/project) and run:

Project-Level Setup

claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http --scope project

This creates a .claude/mcp.json file so the server is available only in this directory.

Global Configuration

Run this command for global configuration:

Global Setup

claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http --scope user

Manual Configuration

You can also manually edit your Claude configuration file.

Location:

Add the Finix MCP server to the mcpServers section:

~/.claude.json

{
  "mcpServers": {
    "finix-redocly-mcp": {
      "type": "http",
      "url": "https://docs.finix.com/mcp"
    }
  }
}

After editing, restart Claude Code to apply the changes.

Using the Finix MCP Server

Once configured, Claude uses the MCP server automatically when you ask Finix-related questions.

Example Prompts

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?" "What does the RETURNED state mean for a Transfer?" "How do I handle declined payments?"

Best Practices

For best results:

  1. Be specific - "How do I create a card Authorization?" is better than "How do payments work?"
  2. Reference API resources - Utilize terms like "Transfer", "Authorization", "Identity", "Merchant" when relevant.
  3. Ask for examples - "Show me an example of..." prompts Claude to pull code samples from documentation.
  4. Mention the environment - Specify "Sandbox" or "Production" if it matters for your question.

Troubleshooting

MCP Server Not Found

If claude mcp list doesn't show finix-redocly-mcp:

  1. Re-run the add command:
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http
  1. Check that your configuration file exists and is valid JSON.

Connection Errors

If Claude reports connection issues:

  1. Check internet connection - Verify you can access docs.finix.com in a browser.

  2. Look for firewall/proxy issues - Corporate networks may block MCP connections.

  3. Try removing and re-adding:

Reset Connection

claude mcp remove finix-redocly-mcp
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http

Claude Not Using Finix Documentation

If Claude seems to guess instead of searching the documentation:

  1. Be explicit - Try "Search the Finix documentation for..." in the prompt.
  2. Check MCP is enabled - Run claude mcp list to verify the server is configured.
  3. Restart Claude Code - A fresh session can help.

Claude Only Returning API Reference (No Guide Content)

If Claude answers with only API endpoint details and misses relevant guide content,

  1. Add the CLAUDE.md instructions - See the Enhancing Guide Access section above to instruct Claude to fetch guide Markdown pages.
  2. Ask explicitly - Try "Check the Finix guides for how to..." to prompt Claude to search for guide content.

Outdated Information

The MCP server uses Finix's published documentation. If you find any outdated information:

The MCP server always shows the latest information from docs.finix.com, which is updated regularly.

Removing the Finix MCP Server

To disconnect Claude Code from Finix documentation:

Remove Finix MCP Server

claude mcp remove finix-redocly-mcp