# Gemini Setup for Finix MCP

![Gemini CLI](/assets/google_gemini_logo.svg.dcfcbb668ffb05fcfd1baee701b87fbc1c85e08f8e1f5a6bd1a4531dd24bfc71.fec90461.png)

This guide walks you through connecting Gemini CLI to the Finix MCP server. After setup, you can ask Gemini questions about Finix APIs and get accurate answers from our documentation.

## Prerequisites

Before you begin, make sure you have:

- **Node.js 20.0.0 or later**
- **A Google account** — Free tier (Gemini Code Assist for individuals) works; no Google Cloud project required
- **Internet connection** — Required to reach `docs.finix.com`


### Installing Gemini CLI

If you don't have Gemini CLI installed yet:


```bash Install Gemini CLI
npm install -g @google/gemini-cli
```

After installing, run `gemini` and select **Sign in with Google** to authenticate via your browser.

Alternatively, you can set a `GEMINI_API_KEY` environment variable from [Google AI Studio](https://aistudio.google.com) instead of using browser-based authentication.

For detailed installation instructions, see the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli).

## Quick Setup

Add the Finix MCP server with a single command:


```bash Add Finix MCP Server
gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp
```

Gemini CLI can now access Finix documentation.

> **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, Gemini 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 Gemini full access to both API docs and guides, add the following to your project's `GEMINI.md` 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 Gemini 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


```bash List MCP Servers
gemini mcp list
```

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

### Test a Query

Start a Gemini CLI session and ask a question about Finix:


```bash Start Gemini CLI
gemini
```

**API Reference test:**

Then try a test prompt:

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


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

## Configuration Options

### Project-Level Configuration

To add the Finix MCP server only to a specific project, navigate to your project directory first:


```bash Project-Level Setup
cd /path/to/your/project
gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp -s project
```

This creates a `.gemini/settings.json` file in your project, so the MCP server is only available when working in that directory.

### Global Configuration

To make the Finix MCP server available in all your projects:


```bash Global Setup
gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp -s user
```

### Manual Configuration

You can also manually edit your Gemini configuration file.

**Global location**: `~/.gemini/settings.json`
**Project location**: `.gemini/settings.json`

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


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

After editing, restart Gemini CLI for changes to take effect.

## Using Finix MCP

Once configured, Gemini automatically uses the MCP server 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 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 Gemini 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 `gemini mcp list` doesn't show `finix-redocly-mcp`:

1. Re-run the add command:

```bash
gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp
```
2. Check your configuration file exists and contains valid JSON


### Connection Errors

If Gemini reports connection issues:

1. **Check internet connection** — Verify you can reach `docs.finix.com` in a browser
2. **Check for firewall/proxy issues** — Corporate networks may block MCP connections
3. **Try removing and re-adding**:

```bash Reset Connection
gemini mcp remove finix-redocly-mcp
gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp
```


### MCP Issues Detected at Startup

If Gemini displays "MCP issues detected. Run /mcp list for status" when starting a session:

1. Run `/mcp list` inside the session to see detailed diagnostics
2. Verify the MCP server URL is correct in your configuration
3. Check that `docs.finix.com` is reachable from your network


### Gemini Not Using Finix Documentation

If Gemini 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** — Run `gemini mcp list` to verify the server is configured
3. **Restart Gemini CLI** — Sometimes a fresh session helps


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

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

1. **Add the `GEMINI.md` instructions** — See the [Enhancing Guide Access](#enhancing-guide-access) section above to instruct Gemini to fetch guide markdown pages
2. **Ask explicitly** — Try "Check the Finix guides for how to..." to prompt Gemini 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 Gemini CLI from Finix documentation:


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

## 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.

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

Developer Quickstart
Start building your Finix integration.

Testing Your Integration
Verify your integration is working correctly.