Observe Community MCP Server

Observe Community MCP Server

A Model Context Protocol (MCP) server that provides LLMs with access to Observe platform functionality through semantic search and LLM-powered dataset intelligence.

Purpose

This MCP server enables LLMs to interact with Observe platform data through a set of 7 tools. It includes dataset discovery capabilities powered by LLM reasoning, OPAL query execution, semantic search for documentation, and AI-powered observability investigations.

Key capabilities:

• Dataset discovery using LLM-powered semantic analysis
• OPAL query execution against Observe datasets
• Vector-based search for OPAL documentation and runbooks
• AI-powered observability investigations with GPT-5 reasoning
• JWT-based authentication with role-based access control

⚠️ DISCLAIMER: This is an experimental MCP server for testing and collaboration. Use at your own risk. A production-ready version, based on a completely different code base, is available to Observe customers.

Table of Contents

• Purpose
• Available MCP Tools
• Quick Start
  • Prerequisites
  • Installation
  • Environment Setup
  • Database Setup
  • Initialize Vector Database
• Running the Server
  • Docker (Recommended)
  • Manual Python Execution
• Authentication Setup
• Using with Claude Desktop
• Architecture Overview
• Dataset Intelligence System
• Maintenance

Available MCP Tools

This MCP server provides 7 core tools for Observe platform access:

Dataset Intelligence

• query_semantic_graph: Find relevant datasets using LLM-powered analysis of query intent and dataset metadata. This uses a chached and semantically enriched dataset metadata.
• list_datasets: List available datasets with filtering options (a direct API call to Observe)
• get_dataset_info: Get detailed schema information about specific datasets (a direct API call to Observe)

Query Execution

• execute_opal_query: Execute OPAL queries against Observe datasets with error handling and multi-dataset support (a direct API call to Observe)

Knowledge & Documentation

• get_relevant_docs: Search Observe documentation, include OPAL language reference (semantic vector search)
• get_system_prompt: Retrieve the system prompt that configures LLMs as an Observe expert

AI-Powered Investigations

• o11y_scout: Autonomous observability investigation agent powered by GPT-5 with reasoning capabilities. Takes a natural language query and executes multi-step investigations using real data from Observe platform tools to provide data-driven analysis and recommendations.

Each tool includes error handling, authentication validation, and structured result formatting.

Quick Start

Prerequisites

• Python 3.11+
• Docker and Docker Compose (recommended)
• Pinecone account with API key
• Observe API credentials (customer ID and token)
• OpenAI API key (for LLM-powered dataset intelligence)

Installation

Environment Setup

Copy the example environment file and configure your credentials:

Required variables:

Database Setup

The server requires a PostgreSQL database with pgvector extension for dataset intelligence functionality. This is automatically configured when using Docker Compose.

Important: The dataset intelligence system requires populating the database with dataset metadata before first use.

Initialize Vector Database

Populate the Pinecone indices with documentation:

Note: If you don't have access to Observe documentation files, contact your Observe representative.

Options for all scripts:

• --force: Recreate the index from scratch
• --verbose: Enable detailed logging

Running the Server

Docker (Recommended)

The server will be available at http://localhost:8000 with automatic health checks and PostgreSQL database.

Manual Python Execution

For development:

Authentication Setup

⚠️ CRITICAL: READ THIS SECTION COMPLETELY

There are two types of authentication mechanisms used in this server:

Observe API authentication (Observe API bearer token) - Uses your Observe API token to access platform data. This token inherits the permissions of the user who created it.

⚠️ IMPORTANT: Once a user is authenticated to the MCP server, they assume the identity of the user who generated the Observe token, not their own identity. Use RBAC and limit the Observe API token to specific roles and permissions you want available to MCP server users.

MCP authentication (MCP bearer token) - Controls access to the MCP server itself. This is necessary because the server exposes resource-intensive APIs (Pinecone, OpenAI).

The MCP server includes basic RBAC with predefined roles: admin, read, write. These do not map to Observe roles and only control MCP server tool access.

Setting up MCP Authentication

Create private and public key files:

This creates:

• private_key.pem - Keep this secret. Used to sign MCP bearer tokens.
• public_key.pem - Add to the server configuration for token verification.

Copy the public key to your .env file:

Generate user tokens:

Security: Keep token expiration times short (hours rather than days).

Local-only deployment: If running locally without public access, you can disable MCP authentication by modifying the server configuration.

Using with Claude Desktop

Add the following to your claude_desktop_config.json:

Network Configuration Note: MCP clients typically restrict HTTP access to localhost only. For internet-accessible deployments, implement an HTTPS reverse proxy with proper DNS configuration and SSL certificates.

The server will be available with 7 MCP tools for dataset discovery, query execution, documentation search, and AI-powered investigations.

Architecture Overview

The MCP server uses a modular architecture:

Technology Stack:

• MCP Server: FastAPI + MCP Protocol
• Dataset Intelligence: PostgreSQL + pgvector + OpenAI GPT-4
• Query Engine: Python asyncio + Observe API
• Vector Search: Pinecone + OpenAI embeddings
• Authentication: JWT + RSA keys
• Caching: PostgreSQL-based dataset metadata caching

Dataset Semantic Search System

The dataset semantic search system uses LLM reasoning to understand user queries and match them with relevant Observe datasets.

How It Works

1. Query Analysis: Analyzes user queries to detect explicit dataset mentions, domain keywords, and intent
2. Candidate Selection: Retrieves relevant datasets from PostgreSQL cache with smart sampling
3. LLM Ranking: Uses GPT-4 to rank datasets based on relevance with detailed explanations
4. Result Enhancement: Applies quality filters and diversity balancing

Key Features

Explicit Dataset Detection: Recognizes when users mention specific datasets by name

Domain Intelligence: Maps query domains to appropriate dataset types

Smart Prioritization: Applies observability expertise

• OpenTelemetry/Span always ranks first for trace/performance queries
• Log datasets prioritized for debugging/error queries
• Database datasets top-ranked for SQL/performance queries

Performance

The system provides dataset recommendations typically within 1-3 seconds, with high accuracy for domain-specific queries. It maintains a local cache of dataset metadata in PostgreSQL for performance.

Maintenance

Update Vector Databases

Monitor Performance

Common Issues

1. No dataset recommendations: Verify OpenAI API key and database population
2. Slow responses: Check PostgreSQL connection and dataset cache
3. Authentication errors: Validate JWT token and public key configuration
4. Missing documentation: Run populate scripts with --force flag

All scripts support --force to recreate indices and --verbose for detailed logging.

Contributing: Issues, feature requests, and pull requests are welcome. This project demonstrates LLM-native observability tooling approaches.