MCP Server Guide

This guide covers the Model Context Protocol (MCP) server in Simba Intelligence, which enables AI assistants and other MCP-compatible clients to securely query your data sources using standardized tooling and OAuth2 PKCE authentication.

Overview

The MCP server exposes Simba Intelligence capabilities as MCP tools that can be consumed by AI assistants (such as Claude Desktop, Cursor, or custom agents) through the Model Context Protocol standard. It runs as a separate deployment alongside the main application.

Key Capabilities

🔧 MCP Tools

Query data sources using natural language
List available data sources and their metadata
Retrieve field-level statistics for data exploration
Get AI-generated follow-up question suggestions

🔐 OAuth2 PKCE Authentication

Secure authorization code flow with Proof Key for Code Exchange (PKCE)
Scoped access tokens tied to user identity and tenant context
Automatic token refresh and rotation
Full multi-tenancy support

Architecture

The MCP server runs as a dedicated deployment with two containers:

┌─────────────────────────────────────────┐
│  MCP Pod                                │
│                                         │
│  ┌───────────┐     ┌────────────────┐   │
│  │  Nginx    │     │  MCP Server    │   │
│  │  Sidecar  │────▶│  Uvicorn)      │   │
│  │  :8000    │     │  :8001         │   │
│  └───────────┘     └────────────────┘   │
│                                         │
└─────────────────────────────────────────┘

Nginx sidecar (port 8000) — Handles path rewriting and exposes OAuth2 well-known endpoints. This is the externally accessible port.
MCP server (port 8001) — FastMCP application running on Gunicorn with Uvicorn workers. Only accessible internally within the pod.

Available MCP Tools

Once connected, MCP clients can use the following tools:

`get_data`

Query a data source using natural language.

Parameter	Type	Required	Description
`question`	string	Yes	Natural language question about the data
`source_id`	string	No	Specific data source to query. If omitted, the system selects the best match

`get_data_sources`

List available data sources accessible to the authenticated user.

Parameter	Type	Required	Description
`max_sources`	integer	No	Maximum number of sources to return

`get_suggested_questions`

Get AI-generated follow-up questions based on available data.

Parameter	Type	Required	Description
`source_id`	string	No	Data source to generate suggestions for
`count`	integer	No	Number of suggestions to return

`get_field_statistics`

Retrieve field-level statistics such as distinct values, min/max ranges, and data distributions.

Parameter	Type	Required	Description
`source_id`	string	Yes	Data source containing the field
`field_name`	string	No	Name of the field to analyze. If omitted, returns statistics for all fields

OAuth2 PKCE Authentication Flow

The MCP server uses OAuth2 with PKCE (S256) for secure client authentication. This flow is designed for public clients that cannot securely store a client secret.

Flow Overview

Discovery    →  Client fetches /.well-known/oauth-authorization-server
Registration →  Client registers at /mcp/register
Authorization → User redirected to /mcp/authorize (with PKCE challenge)
Consent      →  User approves the requested scopes
Token Exchange → Client exchanges auth code + code_verifier for tokens
MCP Calls    →  Client uses access token for MCP tool invocations
Refresh      →  Client uses refresh token when access token expires

OAuth2 Scopes

Scope	Description	Who Gets It
`read:data`	Query data sources and retrieve results	All authenticated users
`write:data`	Write operations	All users with an active role
`admin:users`	User administration	Supervisor role only

Token Lifetimes

Token Type	Lifetime	Notes
Authorization code	10 minutes	Single-use, exchanged for tokens
Access token	1 day	Contains Composer bearer token and user claims
Refresh token	30 days	Rotated on each use for security

Discovery Endpoints

MCP clients discover the OAuth2 configuration through well-known endpoints:

/.well-known/oauth-authorization-server — Returns the authorization server metadata (issuer, endpoints, supported grant types)
/.well-known/oauth-protected-resource — Returns protected resource metadata

Security Features

PKCE S256 — Code challenge verification prevents authorization code interception
Redirect URI validation — Blocks dangerous schemes (javascript:, data:, etc.)
Token rotation — Refresh tokens are rotated on each use; old tokens are invalidated
Session binding — User identity (user_id, tenant_id) is embedded in all tokens
Revocation — Both access and refresh tokens can be revoked, which cascades to related tokens

Deployment Configuration

Helm Values

The MCP server is configured through the Helm chart under the simba.intelligence.mcp section:

simba:
  intelligence:
    mcp:
      baseUrl: "https://your-domain.com"    # External-facing URL for OAuth2 redirects
      uvicornWorkers: 4                      # Number of Uvicorn worker processes
      logLevel: "info"                       # Log level (debug, info, warning, error, critical)
      replicaCount: 1                        # Number of pod replicas

      autoscaling:
        enabled: false
        minReplicas: 1
        maxReplicas: 3
        targetCPUUtilizationPercentage: 80

      image:
        repository: docker.io/insightsoftware/simba-intelligence
        tag: main

      service:
        type: ClusterIP
        port: 8000                           # Nginx proxy port (external)

      resources:
        requests:
          cpu: 250m
          memory: 512Mi
        limits:
          cpu: 1
          memory: 2Gi

      sidecar:                               # Nginx reverse proxy
        image:
          repository: docker.io/nginx
          tag: 1.21-alpine
        resources:
          requests:
            cpu: 50m
            memory: 64Mi

Environment Variables

Variable	Default	Description
`MCP_BASE_URL`	Required	External-facing URL used for OAuth2 PKCE redirect URIs (e.g., `https://your-domain.com`)
`MCP_UVICORN_WORKERS`	`4`	Number of Uvicorn worker processes
`UVICORN_LOG_LEVEL`	`info`	Log level for the MCP server (`debug`, `info`, `warning`, `error`, `critical`)
`APP_MODE`	`web`	Must be set to `mcp` for the MCP server container

⚠️ Important: MCP_BASE_URL must match the externally accessible URL where the MCP server is reachable. This URL is used in OAuth2 redirect URIs and discovery responses. Incorrect values will cause authentication failures.

Network Requirements

The MCP Kubernetes Service exposes port 8000 (Nginx proxy) within the cluster
Ingress or load balancer should route MCP traffic to the service on port 8000
The MCP server requires connectivity to:
- PostgreSQL — For OAuth token storage
- Redis — For caching
- Composer/Discovery — For data source queries

Connecting MCP Clients

Client Configuration

MCP clients connect using the server’s base URL with the /mcp path. The exact configuration depends on the client application. Refer to your MCP client’s documentation for the correct configuration format.

Connection Flow

The MCP client discovers the OAuth2 server via /.well-known/oauth-authorization-server
The client registers itself at /mcp/register
The user is redirected to the Simba Intelligence login page to authenticate
After authentication, the user approves the requested scopes on the consent screen
The client receives an authorization code and exchanges it for access/refresh tokens
The client can now invoke MCP tools with the access token

💡 Pro Tip: The user must have an active Simba Intelligence session (authenticated via the web interface) before the MCP OAuth2 flow can complete. Ensure the user has logged in at least once.

Multi-Tenancy

The MCP server fully supports multi-tenancy:

User identity and tenant context are embedded in all OAuth tokens
All MCP tool invocations are scoped to the authenticated user’s tenant
Data source access respects the same role-based permissions as the web interface
Users in multiple tenants are authenticated in the context of their current active tenant

Troubleshooting

Common Issues

OAuth2 redirect failures:

Verify MCP_BASE_URL matches the externally accessible URL
Ensure the Nginx sidecar is running and proxying correctly
Check that the ingress/load balancer is routing to port 8000

Authentication errors:

Confirm the user has an active Simba Intelligence session
Check that Composer/Discovery is accessible from the MCP pod
Review MCP server logs for token exchange errors

Tool execution failures:

Verify the user has appropriate role permissions for the requested operation
Check connectivity to Composer, PostgreSQL, and Redis
Review logs with UVICORN_LOG_LEVEL=debug for detailed request tracing

Viewing Logs

# Find MCP pods
kubectl get pods -n simba-intelligence | grep mcp

# View MCP server logs
kubectl logs <mcp-pod-name> -c simba-intelligence-mcp -n simba-intelligence

# View Nginx sidecar logs
kubectl logs <mcp-pod-name> -c nginx -n simba-intelligence

Getting Started

Deployment

Operations & Maintenance

Admin Guides

User Guides

Supplementary Resources

MCP Server Guide

MCP Server Guide

Overview

Key Capabilities

Architecture

Available MCP Tools

`get_data`

`get_data_sources`

`get_suggested_questions`

`get_field_statistics`

OAuth2 PKCE Authentication Flow

Flow Overview

OAuth2 Scopes

Token Lifetimes

Discovery Endpoints

Security Features

Deployment Configuration

Helm Values

Environment Variables

Network Requirements

Connecting MCP Clients

Client Configuration

Connection Flow

Multi-Tenancy

Troubleshooting

Common Issues

Viewing Logs

Getting Started

Deployment

Operations & Maintenance

Admin Guides

User Guides

Supplementary Resources

​MCP Server Guide

​Overview

​Key Capabilities

​Architecture

​Available MCP Tools

​get_data

​get_data_sources

​get_suggested_questions

​get_field_statistics

​OAuth2 PKCE Authentication Flow

​Flow Overview

​OAuth2 Scopes

​Token Lifetimes

​Discovery Endpoints

​Security Features

​Deployment Configuration

​Helm Values

​Environment Variables

​Network Requirements

​Connecting MCP Clients

​Client Configuration

​Connection Flow

​Multi-Tenancy

​Troubleshooting

​Common Issues

​Viewing Logs

MCP Server Guide

Overview

Key Capabilities

Architecture

Available MCP Tools

`get_data`

`get_data_sources`

`get_suggested_questions`

`get_field_statistics`

OAuth2 PKCE Authentication Flow

Flow Overview

OAuth2 Scopes

Token Lifetimes

Discovery Endpoints

Security Features

Deployment Configuration

Helm Values

Environment Variables

Network Requirements

Connecting MCP Clients

Client Configuration

Connection Flow

Multi-Tenancy

Troubleshooting

Common Issues

Viewing Logs