Skip to main content

​
Configuration Options

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

​
Basic Structure

{
  "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. 
{
  "url": "https://mcp.notion.com/mcp"
}

​
Enabled (Optional)

Toggle server availability without deleting configuration. Defaults to true. 
{
  "enabled": true  // Server active
}

{
  "enabled": false  // Server disabled (config preserved)
}

​
Headers (Optional)

Custom HTTP headers for authentication or metadata: 
{
  "headers": {
    "Authorization": "Bearer your-token",
    "X-API-Key": "your-api-key",
    "X-Environment": "production"
  }
}
Use OAuth instead of static headers for sensitive operations when possible.

​
Server Name

The key in mcpServers must be unique and descriptive: 
{
  "mcpServers": {
    "notion": { ... },           // ✓ Clear
    "github-issues": { ... },    // ✓ Specific
    "company-wiki": { ... }      // ✓ Descriptive
  }
}

​
Configuration Examples

​
With API Key

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

​
Development & Production

{
  "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 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 🔒 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 🔒 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 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
  • Try connecting different types of servers
  • Monitor tool usage and performance
  • Implement your own MCP server
⌘I