# Connect Claude to Finix MCP

Claude Logo
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:

- **Claude Code installed** - Anthropic's CLI tool for AI-assisted development.
- **Internet connection** - Required to reach [docs.finix.com](https://docs.finix.com/).


### Installing Claude Code

If you don't have Claude Code installed yet:


```bash Install Claude Code
npm install -g @anthropic-ai/claude-code
```

Or with Homebrew on macOS:


```bash Install with Homebrew
brew install claude-code
```

For detailed installation instructions, see [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).

## Quick Setup

Run this command to add the Finix MCP server:


```bash
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](#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:


```markdown
## 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


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


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


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


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

- macOS/Linux: `~/.claude.json`
- Windows: `%USERPROFILE%\.claude.json`


Add the Finix MCP server to the `mcpServers` section:


```json ~/.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:

```bash
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http
```
2. 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](https://docs.finix.com/) in a browser.
2. **Look for firewall/proxy issues** - Corporate networks may block MCP connections.
3. **Try removing and re-adding**:

```bash 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](#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:

- Check [docs.finix.com](https://docs.finix.com) for the latest published documentation.
- If you notice a discrepancy, contact the [Finix Support Team](mailto:support@finix.com) or your Finix representative for a definitive answer.


The MCP server always shows the latest information from [docs.finix.com](https://docs.finix.com), which is updated regularly.

## Removing the Finix MCP Server

To disconnect Claude Code from Finix documentation:


```bash Remove Finix MCP Server
claude mcp remove finix-redocly-mcp
```