Observe Experimental MCP

🚀 Observe MCP Server

A Model Context Protocol (MCP) server that offers access to Observe API functionality, OPAL query assistance, and troubleshooting runbooks via vector search.

🚀 Quick Start

This Observe MCP Server is designed to interface with technically capable LLM models, offering seamless access to the Observe platform's features. To get started, follow the steps below to set up and run the server.

Prerequisites

• Python 3.8+
• A Pinecone account with an API key
• Observe API credentials

Installation

First, clone the repository:

git clone https://github.com/rustomax/observe-experimental-mcp.git
cd observe-experimental-mcp

Create a virtual environment and activate it:

python3 -m venv .venv
source .venv/bin/activate

Install the required dependencies:

pip install -r requirements.txt

Environment Setup

Copy .env.template to .env and fill in the values.

Populating Vector Database

Documentation Index

python populate_docs_index.py

Runbooks Index

python populate_runbooks_index.py

Running the Server

python observe_server.py

✨ Features

• Direct Interaction: Interfaces directly with the Observe platform in an LLM-friendly way, avoiding the use of LLMs for internal functions to prevent private data leakage.
• Comprehensive Functionality: Enables a wide range of operations, including executing OPAL queries, exporting worksheet data, listing and retrieving dataset information, providing OPAL query assistance, and managing monitors.
• Semantic Search: Leverages Pinecone as a vector database for semantic search across OPAL reference documentation and troubleshooting runbooks.
• Multi - Data Type Troubleshooting: Facilitates comprehensive troubleshooting using multiple data types such as logs, metrics, and traces.
• Contextual Data Integration: Allows integration with contextual data like GitHub commits, business metrics, and customer journeys.
• Access to Specialized Information: Provides access to vectorized documentation and specialized runbooks for in - depth information on OPAL queries, Observe concepts, and best practices.

📦 Installation

Prerequisites

• Python 3.8+
• Pinecone account with an API key
• Observe API credentials

Steps

1. Clone the Repository

git clone https://github.com/rustomax/observe-experimental-mcp.git
cd observe-experimental-mcp

2. Create and Activate a Virtual Environment

python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Environment Setup Copy .env.template to .env and fill in the values.
5. Populate the Vector Database
   • Documentation Index

python populate_docs_index.py

- **Runbooks Index**

python populate_runbooks_index.py

💻 Usage Examples

Basic Usage

To run the server:

python observe_server.py

Advanced Usage

You can modify the port and transport method in the observe_server.py file if needed. For example, to change the port from the default 8000:

# Modify the relevant part in observe_server.py
# ... existing code ...
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8080)  # Change port to 8080
# ... existing code ...

📚 Documentation

Key Components

Available MCP Tools

Observe API Tools

• execute_opal_query: Execute an OPAL query on a dataset
• export_worksheet: Export data from an Observe worksheet with flexible time parameters (defaults to 15m interval)
• list_datasets: List available datasets in Observe
• get_dataset_info: Get detailed information about a dataset
• create_monitor: Create a new monitor in Observe
• list_monitors: List all monitors in Observe
• get_monitor: Get detailed information about a specific monitor

Documentation and Assistance Tools

• get_relevant_docs: Get relevant documentation for a query using Pinecone vector search

Troubleshooting Tools

• recommend_runbook: Analyze a user query and recommend the most relevant troubleshooting runbook

System Tools

• get_system_prompt: Get the system prompt for the Observe MCP server

Worksheet Export Tool

Parameters

• worksheet_id (required): The ID of the worksheet to export
• time_range (optional): Time range for the export (e.g., "15m", "1h", "24h"). Defaults to "15m" if no time parameters are provided
• start_time (optional): Start time in ISO format (e.g., "2025-07-21T00:00:00Z")
• end_time (optional): End time in ISO format (e.g., "2025-07-22T00:00:00Z")

Time Parameter Combinations

1. Interval only (relative to now): export_worksheet("42566610", time_range="1h")
2. Start and end times: export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", end_time="2025-07-22T00:00:00Z")
3. Start time + interval: export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", time_range="24h")
4. End time + interval: export_worksheet("42566610", end_time="2025-07-22T00:00:00Z", time_range="24h")

Response Format

The tool returns data in NDJSON (newline - delimited JSON) format. For large datasets, responses are automatically truncated with a summary showing the first 50 lines and total row count.

Vector Database Helpers

The pinecone_reference_helpers.py module provides functions to query the Pinecone vector database:

• initialize_pinecone() - Initialize the Pinecone client and ensure the index exists
• get_embedding(pc, text, is_query) - Get embedding for a text using Pinecone's integrated embedding model
• semantic_search(query, n_results) - Perform semantic search using Pinecone
• list_all_entities() - List all documents in the Pinecone index
• get_document_by_id(doc_id) - Get a specific document by ID

Architecture and How It Works

Indexing Process

Runtime Query Process

Documentation Assistance Flow

1. The LLM assistant calls the MCP server with a user query for documentation.
2. The get_relevant_docs function is called to process the query.
3. The system generates an embedding for the query using Pinecone's inference API.
4. This embedding is used to search the "observe - docs" index for relevant document chunks.
5. The system groups chunks by source document and calculates relevance scores.
6. Complete documents are retrieved from the filesystem and returned, ranked by relevance.

Runbook Recommendation Flow

1. The LLM assistant calls the MCP server with a user troubleshooting query.
2. The recommend_runbook function is called to process the query.
3. The system generates an embedding for the query using Pinecone's inference API.
4. This embedding is used to search the "observe - runbooks" index for relevant runbook chunks.
5. The system groups chunks by source runbook and calculates average relevance scores.
6. The most relevant complete runbook is retrieved from the filesystem and returned to the user.

Advantages of the Vector Database Approach

• Semantic Understanding: Vector search understands the meaning of queries, not just keywords.
• Fuzzy Matching: Can find relevant results even with typos or different wording.
• Relevance Ranking: Results are ranked by semantic similarity.
• Extensibility: Easy to add new documents without schema changes.
• Direct Use of Markdown: Uses markdown files as the source of truth.
• Integrated Embeddings: Uses Pinecone's built - in embedding model, eliminating the need for OpenAI API keys.
• Scalability: Pinecone provides a managed, scalable vector database service.
• Chunking with Full Document Retrieval: Optimizes search accuracy through chunking while providing complete context through full document retrieval.

Setting up Authentication

There are two types of authentication mechanisms used in this server: Observe API authentication and MCP authentication.

⚠️ Important Note

Observe API authentication (Observe API bearer token) inherits the context of the token that is used to authenticate the user who created the token to the Observe platform. This token should be considered secret and is never exposed to the MCP users. Once a user is authenticated to the MCP server, they will NOT assume their identity in Observe, but the identity of the user who generated the Observe token. Make sure to use RBAC and limit access for the Observe API token to specific roles and permissions that you want to make available to the Observe MCP server users.

⚠️ Important Note

MCP authentication (MCP bearer token) is used to authorize the user to access and use the functionality of the MCP server. This token is generated by the server administrator and is exposed to the MCP users, for instance to use in Claude Desktop or other MCP clients. This second layer of authentication is necessary because the server exposes resource - intensive APIs (like Pinecone) to MCP users. It allows server administrators to control access and prevent resource abuse.

IMPORTANT: Current implementation of the MCP server also includes a basic RBAC via predefined roles: admin, read, write. These DO NOT map into any roles in Observe. They are used to control access to the MCP server tools.

Local - only deployment: If you're running the server locally without public access, you can disable MCP authentication by modifying observe_server.py and removing the Authorization header from the MCP client configuration.

Setting up MCP authentication

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

Copy the public key and add it to the .env file:

# Public PEM key for MCP token verification
PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----
<your_public_key_here>
-----END PUBLIC KEY-----"

Sign the bearer token with the private key:

./generate_mcp_token.sh 'user@example.com' 'admin,read,write' '4H'

⚠️ Important Note

Keep token expiration times short (hours rather than days). Avoid issuing long - lived tokens to minimize security risks.

Using in Claude Desktop

Add the following to your claude_desktop_config.json if you are running the MPC server locally, or provide the URL if you exposed the server publically.

⚠️ Important Note

MCP clients typically restrict HTTP access to localhost only. For internet - accessible deployments, implement an HTTPS reverse proxy (Nginx, Caddy, etc.) with proper DNS configuration and SSL certificates.

{
  "mcpServers": {
    "observe-epic": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "http://localhost:8000/sse",
        "--header",
        "Authorization: Bearer bearer_token"
      ]
    }
  }
}

💡 Usage Tip

The server runs on port 8000 by default. You can modify the port in the observe_server.py file if needed. The server uses Server - Sent Events (SSE) transport by default, streaming responses as they're generated for improved efficiency with large payloads. Transport method can be modified in observe_server.py if needed.

Making the Most of the MCP Server

Use a Smart Client LLM

The Observe MCP server is designed to work with technically capable LLM models, specifically tested with Claude Sonnet 3.7 and Claude Sonnet 4. It assumes the client LLM will provide necessary intelligence to use the available tools most effectively.

Understand the Ideal Flow of Events

1. The MCP client (i.e. Claude Desktop or any other LLM) connects to the MCP server.
2. The MCP client discovers available tools and their descriptions.
3. The MCP server attempts to convince the model to use a predefined system prompt to configure itself as an Observe expert.
4. The LLM parses the query and decides which path to follow:
   • For simple questions related to Observe functionality, the LLM will leverage get_relevant_docs tool repeatedly to do semantic lookups in the Pinecone vector database to understand and generate a response.
   • For more complex troubleshooting and investigative tasks, it will first ask the MCP server for a relevant runbook recommendation and then use the runbook to guide its investigative process.
5. It will use other tools to craft and run Observe queries, retrieve dataset lists and information, list and create monitors. If it struggles, it will try to lookup relevant documentation to guide itself.

Hard - Code the System Prompt

To ensure the most consistent use of the MCP server, hardcode the system prompt into your LLM configuration, do not rely on the MCP server to configure the model.

Craft Effective Prompts

Prompt engineering still applies! You can speed up the investigations by crafting effective prompts, including clear objectives, specifying time ranges, identifying relevant datasets or systems, and defining the expected output format.

Use Runbooks to Guide LLMs

Create, update or delete runbooks as needed. Tweak them to your particular environment or use - cases. Use LLMs to improve your runbooks.

Remind LLMs to Use Tools

If the LLM becomes "forgetful" and stops using available tools effectively, remind it to use relevant tools like get_dataset_info and get_relevant_docs.

🔧 Technical Details

This server is designed to work with technically capable LLM models, specifically tested with Claude Sonnet 3.7 and Claude Sonnet 4. It interfaces directly with the Observe platform in an LLM - friendly way, avoiding the use of LLMs for internal functions to prevent private data leakage. The server leverages Pinecone as a vector database for semantic search across OPAL reference documentation and troubleshooting runbooks. It uses a multi - index vector database architecture for documentation assistance and runbook recommendations.

📄 License

⚠️ Important Note

This is an experimental and unsupported MCP server created for testing and collaboration with Observe AI design partners. Observe bears no liability for any use of this server and does not support it in any way. A separate production - ready MCP server is under development by Observe.