# Connect Gemini to Finix MCP

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

## Prerequisites

Before you begin, make sure you have:

- **Node.js 20.0.0 or later**.
- **A Google account** - The free tier (Gemini Code Assist for individuals) works; no Google Cloud project needed.
- **Internet connection** - Required to reach [docs.finix.com](https://docs.finix.com).


### Installing the Gemini CLI

If you do not have the 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, set a `GEMINI_API_KEY` environment variable from [Google AI Studio](https://aistudio.google.com) to avoid browser-based authentication.

Refer to the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for detailed installation instructions.

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

The Gemini CLI now accesses 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 lacks a 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 lets Gemini access Markdown guides and API references via MCP, ensuring full access to Finix docs.

## Verify the Connection

After adding the MCP server, verify it is working:

### Check MCP Status


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

You should see `finix-redocly-mcp` listed among 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 exact 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 and run the `gemini mcp add` command:


```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, making the MCP server available only 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 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 to apply the changes.

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

1. **Be specific** - "How do I create a card Authorization?" works better than "How 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 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 `gemini mcp add` command:

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


### Connection Errors

If Gemini reports connection issues:

1. **Check internet connection** - Verify you can access [docs.finix.com](https://docs.finix.com/) from a browser.
2. **Check firewall/proxy issues** - Corporate networks may block MCP connections.
3. **Try removing and adding again**:

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

When starting a session, if Gemini shows:

> *"MCP issues detected. Run /mcp list for status."*


Perform the following:

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](https://docs.finix.com/) is reachable from your network.


### Gemini Not Using Finix Documentation

If Gemini guesses instead of searching the documentation:

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


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

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

1. **Add the `GEMINI.md` instructions** - See the [Enhancing Guide Access](#enhancing-guide-access) section above to have Gemini fetch full Markdown files.
2. **Ask explicitly** - Try "Check the Finix guides for how to..." to prompt Gemini 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 MCP Server

To disconnect Gemini CLI from the Finix MCP server:


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