### Server Installation and Usage - Bash

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

Instructions for local development setup, building, and running the MCP server. The server can be installed via npx, Smithery, or built from source. Commands include installation for Claude Desktop, cloning the repository, installing dependencies, building, running in development mode, and packaging for distribution.

```bash
# Install via Smithery for Claude Desktop
npx -y @smithery/cli install @AgentOps-AI/agentops-mcp --client claude

# Local development build
git clone https://github.com/AgentOps-AI/agentops-mcp.git
cd agentops-mcp
npm install
npm run build

# Run the server
npm start

# Development mode with auto-reload
npm run dev

# Package for distribution
npm pack
```

--------------------------------

### Build and Run AgentOps MCP Server Locally

Source: https://github.com/agentops-ai/agentops-mcp/blob/main/README.md

Steps to set up and run the AgentOps MCP server for local development. This includes cloning the repository, installing dependencies, building the project, and packaging it.

```bash
# Clone and setup
git clone https://github.com/AgentOps-AI/agentops-mcp.git
cd mcp
npm install

# Build the project
npm run build

# Run the server
npm pack
```

--------------------------------

### Install AgentOps MCP Server via Smithery CLI

Source: https://github.com/agentops-ai/agentops-mcp/blob/main/README.md

Command to install the agentops-mcp server using the Smithery CLI. This command is designed for automatic installation with clients like Claude.

```bash
npx -y @smithery/cli install @AgentOps-AI/agentops-mcp --client claude
```

--------------------------------

### Environment Configuration - Bash/Env

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

Setup for environment variables for local development or deployment. The AGENTOPS_API_KEY is essential for authentication and can be configured in a .env file or exported directly in the shell environment. An optional HOST variable can override the default API host.

```dotenv
# .env file
AGENTOPS_API_KEY="your-agentops-api-key-here"

# Optional: Override default API host
HOST="https://api.agentops.ai"

```

```bash
# Shell export
export AGENTOPS_API_KEY="your-agentops-api-key-here"
```

--------------------------------

### Error Handling Pattern - JavaScript

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

Standard error response format returned by tools when operations fail. Errors are returned as JSON objects with descriptive messages, avoiding exceptions. Examples include authentication errors, not authenticated errors, API request errors, and network errors.

```javascript
// Authentication error
{
  "error": "No project API key available. Please provide a project API key."
}

// Not authenticated error (when calling tools before auth)
{
  "error": "Not authenticated. Please use the 'auth' tool first with your AgentOps API key."
}

// API request error
{
  "error": "Request failed with status code 404"
}

// Network error
{
  "error": "Network Error: connect ETIMEDOUT"
}
```

--------------------------------

### Get Complete Trace Tool - JavaScript

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

Retrieves exhaustive trace information including all child spans and their full details and metrics. Unlike get_trace which only returns span IDs, this tool recursively fetches complete information for every span in the trace hierarchy. It requires a trace_id as input and returns a detailed trace object.

```javascript
// Tool invocation
{
  "name": "get_complete_trace",
  "arguments": {
    "trace_id": "trace_abc123def456"
  }
}

// Response with fully populated spans
{
  "trace_id": "trace_abc123def456",
  "session_id": "session_xyz789",
  "start_time": "2025-10-24T10:15:30.000Z",
  "end_time": "2025-10-24T10:16:45.000Z",
  "status": "completed",
  "tags": ["production", "chatbot"],
  "spans": [
    {
      "span_id": "span_111aaa222bbb",
      "trace_id": "trace_abc123def456",
      "name": "llm_call",
      "kind": "llm",
      "start_time": "2025-10-24T10:15:30.500Z",
      "end_time": "2025-10-24T10:15:45.200Z",
      "attributes": {
        "model": "gpt-4",
        "provider": "openai"
      },
      "metrics": {
        "duration_ms": 14700,
        "token_count": 998,
        "cost_usd": 0.0189
      }
    },
    {
      "span_id": "span_333ccc444ddd",
      "trace_id": "trace_abc123def456",
      "parent_span_id": "span_111aaa222bbb",
      "name": "tool_execution",
      "kind": "tool",
      "metrics": {
        "duration_ms": 3200
      }
    }
  ],
  "metrics": {
    "duration_ms": 75000,
    "token_count": 1523,
    "cost_usd": 0.0234
  }
}
```

--------------------------------

### Configure MCP Client with AgentOps Server

Source: https://github.com/agentops-ai/agentops-mcp/blob/main/README.md

This configuration snippet shows how to set up the MCP client to connect to the AgentOps MCP server. It specifies the command to run the server, arguments, and environment variables, including the AGENTOPS_API_KEY.

```json
{
    "mcpServers": {
        "agentops-mcp": {
            "command": "npx",
            "args": ["agentops-mcp"],
            "env": {
              "AGENTOPS_API_KEY": ""
            }
        }
    }
}
```

--------------------------------

### Authenticate AgentOps Project with API Key

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

This tool authenticates with AgentOps using a project API key and manages JWT tokens for session establishment. It can be triggered manually or automatically on server startup if the API key is provided via environment variables. Handles successful authentication, pre-existing sessions, and authentication failures.

```javascript
// Tool invocation in MCP client
{
  "name": "auth",
  "arguments": {
    "api_key": "your-agentops-project-api-key"
  }
}

// Successful response
{
  "success": true,
  "message": "Authentication successful",
  "project": "My AI Agent Project"
}

// Already authenticated response
{
  "success": true,
  "message": "Already authenticated",
  "source": "Previously authenticated (likely from environment variable on startup)"
}

// Error response
{
  "error": "Authentication failed: Invalid API key"
}
```

--------------------------------

### MCP Client Configuration - JSON

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

Configuration for integrating the AgentOps MCP server with MCP-compatible clients. The server runs as a child process and communicates via stdio. This JSON configuration specifies the command, arguments, and environment variables for the MCP server.

```json
{
  "mcpServers": {
    "agentops-mcp": {
      "command": "npx",
      "args": ["agentops-mcp"],
      "env": {
        "AGENTOPS_API_KEY": "your-agentops-project-api-key"
      }
    }
  }
}
```

--------------------------------

### Programmatic Server Usage - TypeScript

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

Direct integration of the MCP server in TypeScript/JavaScript applications using the official MCP SDK. The server communicates over stdio transport. Initialization involves creating a Server instance and connecting it with a StdioServerTransport. The API key is automatically loaded from the environment.

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Server initialization
const server = new Server({
  name: "agentops-mcp",
  version: "0.3.5"
});

// Set up transport
const transport = new StdioServerTransport();

// Connect server
await server.connect(transport);

// Server automatically loads AGENTOPS_API_KEY from environment
// and authenticates on startup if available

```

--------------------------------

### Retrieve Specific AI Agent Trace Details

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

This tool fetches comprehensive trace information, including metadata and performance metrics, for a given trace ID. It retrieves trace details and associated metrics concurrently and combines them into a single, structured response object. Requires a valid trace ID as input.

```javascript
// Tool invocation
{
  "name": "get_trace",
  "arguments": {
    "trace_id": "trace_abc123def456"
  }
}

// Response
{
  "trace_id": "trace_abc123def456",
  "session_id": "session_xyz789",
  "start_time": "2025-10-24T10:15:30.000Z",
  "end_time": "2025-10-24T10:16:45.000Z",
  "status": "completed",
  "tags": ["production", "chatbot"],
  "spans": [
    {
      "span_id": "span_111aaa222bbb",
      "name": "llm_call"
    },
    {
      "span_id": "span_333ccc444ddd",
      "name": "tool_execution"
    }
  ],
  "metrics": {
    "duration_ms": 75000,
    "token_count": 1523,
    "cost_usd": 0.0234,
    "error_count": 0
  }
}
```

--------------------------------

### Fetch Detailed Information for a Specific AI Agent Span

Source: https://context7.com/agentops-ai/agentops-mcp/llms.txt

This tool retrieves detailed information about an individual span within an AI agent's trace, including its specific metrics like execution time, token usage, and encountered errors. Spans represent discrete operations in the agent's execution flow. Requires a valid span ID as input.

```javascript
// Tool invocation
{
  "name": "get_span",
  "arguments": {
    "span_id": "span_111aaa222bbb"
  }
}

// Response
{
  "span_id": "span_111aaa222bbb",
  "trace_id": "trace_abc123def456",
  "parent_span_id": null,
  "name": "llm_call",
  "kind": "llm",
  "start_time": "2025-10-24T10:15:30.500Z",
  "end_time": "2025-10-24T10:15:45.200Z",
  "status": "success",
  "attributes": {
    "model": "gpt-4",
    "provider": "openai",
    "prompt_tokens": 842,
    "completion_tokens": 156
  },
  "metrics": {
    "duration_ms": 14700,
    "token_count": 998,
    "cost_usd": 0.0189
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.