> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Reference

> Configuration options, troubleshooting, and advanced topics

## Configuration Options

MCP servers are configured using JSON in Settings. Here are all available options:

### Basic Structure

```json theme={null}
{
  "mcpServers": {
    "server-name": {
      "url": "https://example.com/mcp",
      "enabled": true,
      "headers": {
        "X-API-Key": "optional-key"
      }
    }
  }
}
```

### URL (Required)

The MCP server endpoint. Must be a valid HTTPS/HTTP URL.

```json theme={null}
{
  "url": "https://mcp.notion.com/mcp"
}
```

### Enabled (Optional)

Toggle server availability without deleting configuration. Defaults to `true`.

```json theme={null}
{
  "enabled": true  // Server active
}
```

```json theme={null}
{
  "enabled": false  // Server disabled (config preserved)
}
```

### Headers (Optional)

Custom HTTP headers for authentication or metadata:

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer your-token",
    "X-API-Key": "your-api-key",
    "X-Environment": "production"
  }
}
```

<Note>
  Use OAuth instead of static headers for sensitive operations when possible.
</Note>

### Server Name

The key in `mcpServers` must be unique and descriptive:

```json theme={null}
{
  "mcpServers": {
    "notion": { ... },           // ✓ Clear
    "github-issues": { ... },    // ✓ Specific
    "company-wiki": { ... }      // ✓ Descriptive
  }
}
```

## Configuration Examples

### With API Key

```json theme={null}
{
  "mcpServers": {
    "internal-api": {
      "url": "https://internal.company.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      },
      "enabled": true
    }
  }
}
```

### Development & Production

```json theme={null}
{
  "mcpServers": {
    "api-dev": {
      "url": "https://dev-api.example.com/mcp",
      "enabled": false
    },
    "api-prod": {
      "url": "https://api.example.com/mcp",
      "enabled": true
    }
  }
}
```

## Transport Types

TextQL supports two MCP transports, auto-detected during connection:

* **SSE (Server-Sent Events)**: For streaming and real-time updates
* **HTTP**: For standard request-response patterns

You don't need to specify the transport type—TextQL negotiates automatically.

## How Tools Work

### Tool Discovery

When a server connects:

1. TextQL requests available tools via MCP protocol
2. Server returns tool definitions (name, description, schema)
3. Tools register in Ana's system
4. Tools become immediately available to Ana

## Authentication

Many servers require OAuth 2.0 authentication. See [Getting Started](/core/how-it-works/mcp/getting-started#step-4-authenticate-if-required) for the authentication walkthrough.

### Token Management

TextQL manages tokens automatically:

* **Access tokens**: For API requests
* **Refresh tokens**: For obtaining new access tokens
* **Automatic refresh**: When tokens expire, no user action needed

**When refresh fails**: You'll see the authentication badge and need to re-authenticate.

## Troubleshooting

### Connection Issues

**Server Won't Connect**

* Verify URL is correct and accessible
* Check if server is running: `curl -v https://your-server.com/mcp`
* Ensure firewall allows the connection

**URL Validation Error**

TextQL blocks private IPs for security:

* Loopback: `127.0.0.1`, `localhost`
* Private IPs: `10.x.x.x`, `192.168.x.x`, `172.16.x.x`

Fix: Use public URLs or tunneling (ngrok, Cloudflare Tunnel) for development

### Authentication Issues

**OAuth Popup Blocked**

* Enable pop-ups for your TextQL domain in browser settings

**OAuth Flow Fails**

* Ensure redirect URI is whitelisted: `https://app.textql.com/oauth-callback?server_id=<id>`
* Check server OAuth config
* Test discovery: `curl https://your-server.com/.well-known/oauth-authorization-server`

**Token Refresh Fails**

* Ensure OAuth server returns refresh tokens with `refresh_token` field

### Tool Issues

**No Tools Discovered**

* Complete authentication if the authentication badge is shown
* Test endpoint: `curl -X POST https://your-server.com/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'`
* Verify tool format matches MCP specification

**Tool Execution Fails**

* Check required parameters are provided
* Review server logs for errors
* Re-authenticate if tokens expired
* Ensure tool descriptions are clear

**Tools Don't Appear in Ana**

* Verify server is enabled
* Check authentication is complete
* Ensure tool descriptions help Ana understand when to use them

## Getting Help

Contact [support@textql.com](mailto:support@textql.com) with:

* Server configuration (remove sensitive data)
* Error messages from TextQL UI and server logs
* Steps to reproduce the issue

## Technical Details

### Transport Protocols

**SSE (Server-Sent Events)**:

* Long-lived HTTP connection
* Server pushes updates to client
* Ideal for streaming responses
* Automatic reconnection

**HTTP**:

* Standard request-response
* Simpler to implement
* Works with all HTTP infrastructure
* Good for non-streaming use cases

## Next Steps

* [Go back to Getting Started](/core/how-it-works/mcp/getting-started)
* Try connecting different types of servers
* Monitor tool usage and performance
* Implement your own MCP server