# Cursor Setup for Finix MCP

![Cursor](/assets/cursor_logo.svg.a474c8ad835fcedf7acb9a6b324f11e19d32b3695e77bb0cacd061d88c951951.fec90461.png)

This guide walks you through connecting Cursor to the Finix MCP server. After setup, you can ask Cursor questions about Finix APIs and get accurate answers from our documentation directly in your editor.

## Prerequisites

Before you begin, make sure you have:

- **Cursor Pro plan or above** — MCP is not available on the free Hobby plan
- **Internet connection** — Required to reach `docs.finix.com`


### Installing Cursor

If you don't have Cursor installed yet, download it from [cursor.com](https://www.cursor.com) and follow the installation instructions for your platform.

## Quick Setup

You can add the Finix MCP server through the Cursor settings UI or by editing a config file.

### Option A: Settings UI

1. Open Cursor Settings (**Cmd+Shift+J** on Mac, or click the gear icon)
2. Navigate to **Tools & MCP**
3. Click **+ Add new MCP server**
4. Enter the following details:
  - **Name**: `finix-redocly-mcp`
  - **URL**: `https://docs.finix.com/mcp`
5. The server appears in the MCP list with a green status indicator when connected


### Option B: Config File

Create or edit `.cursor/mcp.json` in your project root:


```json .cursor/mcp.json
{
    "mcpServers": {
        "finix-redocly-mcp": {
            "url": "https://docs.finix.com/mcp"
        }
    }
}
```

Cursor picks up the config automatically — no restart required.

> **Note:** The MCP server's `search` tool 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, Cursor can fetch the markdown version of any guide using the `.md` URL pattern (see [Enhancing Guide Access](#enhancing-guide-access) below).


## Enhancing Guide Access

The MCP server can search guides but doesn't have a dedicated tool to retrieve their full content. To give Cursor full access to both API docs and guides, add the following to your project's Cursor rules (`.cursor/rules` file) or system prompt:


```markdown
## 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 Cursor to combine the MCP server tools (for API reference) with direct markdown fetching (for guides), giving it full access to all Finix documentation.

## Verify the Connection

After adding the MCP server, verify it's working:

### Check MCP Status

1. Open Cursor Settings (**Cmd+Shift+J**)
2. Navigate to **Tools & MCP**
3. Confirm `finix-redocly-mcp` shows a green status indicator


### Test a Query

Open a Cursor chat session and ask a question about Finix:

**API Reference test:**

> "What authentication method does the Finix API use?"


If Cursor 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 Cursor responds with details from the seller onboarding guide (not just API endpoint info), guide access is working correctly.

## Configuration Options

### Project-Level Configuration

To share the Finix MCP server with your team, add the config to your project and commit it to your repository:


```json .cursor/mcp.json (project root)
{
    "mcpServers": {
        "finix-redocly-mcp": {
            "url": "https://docs.finix.com/mcp"
        }
    }
}
```

This makes the MCP server available to anyone who opens the project in Cursor.

### Global Configuration

To make the Finix MCP server available across all your projects, add the config to your home directory:


```json ~/.cursor/mcp.json
{
    "mcpServers": {
        "finix-redocly-mcp": {
            "url": "https://docs.finix.com/mcp"
        }
    }
}
```

### Toggle Without Removing

You can enable or disable the Finix MCP server from **Settings > Tools & MCP** without deleting the configuration. This is useful for temporarily disabling the server without losing your setup.

## Using Finix MCP

Once configured, Cursor automatically uses the MCP server when you ask Finix-related questions in chat or with the agent.

### 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 the best results:

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


## Troubleshooting

### Server Not Connecting

If the Finix MCP server doesn't show a green status indicator:

1. **Check the URL** — Verify the URL is exactly `https://docs.finix.com/mcp`
2. **Check internet connection** — Verify you can reach `docs.finix.com` in a browser
3. **Check your plan** — MCP requires a Cursor Pro plan or above


### Connection Errors

If Cursor reports connection issues:

1. **Check for firewall/proxy issues** — Corporate networks may block MCP connections
2. **Check MCP logs** — Open the Output panel (**Cmd+Shift+U**) and select **MCP Logs** from the dropdown to see detailed error messages
3. **Try the mcp-remote bridge** — If you experience transport negotiation issues, use the stdio bridge as a workaround:

```json .cursor/mcp.json
{
    "mcpServers": {
        "finix-redocly-mcp": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://docs.finix.com/mcp"]
        }
    }
}
```


### Cursor Not Using Finix Documentation

If Cursor seems to be guessing instead of searching documentation:

1. **Be explicit** — Try "Search the Finix documentation for..." in your prompt
2. **Check MCP is enabled** — Go to **Settings > Tools & MCP** and verify the server is enabled
3. **Start a new chat** — Sometimes a fresh chat session helps


### Cursor Only Returning API Reference (No Guide Content)

If Cursor answers with only API endpoint details and misses relevant guide content:

1. **Add Cursor rules** — See the [Enhancing Guide Access](#enhancing-guide-access) section above to instruct Cursor to fetch guide markdown pages
2. **Ask explicitly** — Try "Check the Finix guides for how to..." to prompt Cursor to search for guide content


### Outdated Information

The MCP server queries Finix's published documentation. If you notice outdated information:

1. Check [docs.finix.com](https://docs.finix.com) directly to verify current documentation
2. The MCP server reflects published docs, which are updated regularly


## Removing the MCP Server

To disconnect Cursor from Finix documentation:

1. Open Cursor Settings (**Cmd+Shift+J**)
2. Navigate to **Tools & MCP**
3. Remove `finix-redocly-mcp` from the list


Or delete the `finix-redocly-mcp` entry from your `.cursor/mcp.json` file.

## Next Steps

Finix MCP Server Overview
Learn more about what the Finix MCP server can do.

ChatGPT Setup
Step-by-step guide to connect ChatGPT to the Finix MCP server.

Claude Code Setup
Step-by-step guide to connect Claude Code to the Finix MCP server.

Gemini CLI Setup
Step-by-step guide to connect Gemini CLI to the Finix MCP server.

Developer Quickstart
Start building your Finix integration.

Testing Your Integration
Verify your integration is working correctly.