Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt

Use this file to discover all available pages before exploring further.

Observability gives you visibility into your agent’s behavior in production, enabling debugging, performance optimization, and understanding of how your agents use tools and interact with LLMs.

​
What Gets Traced

When observability is enabled, mcp-use automatically captures:
  • Full execution traces: Complete agent workflow from start to finish
  • LLM calls: Model usage, prompts, completions, and token counts
  • Tool execution: Which tools were called, with what parameters, and their results
  • Performance metrics: Execution times for each step
  • Errors and exceptions: Full context when things go wrong
  • Conversation flow: Multi-turn conversation tracking

​
Langfuse Integration

Langfuse is an open-source LLM observability platform

​
Setup Langfuse

​
Set Environment Variables

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."

​
Start Using

// Langfuse automatically initializes when mcp-use is imported
import { MCPAgent, MCPClient } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'
import { config } from 'dotenv'

config() // Load Langfuse environment variables

const client = new MCPClient({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/allowed/files']
    }
  }
})

const llm = new ChatOpenAI({ model: 'gpt-4' })
const agent = new MCPAgent({
  llm,
  client,
  maxSteps: 30
})

// All agent runs are automatically traced!
const result = await agent.run("Analyze the sales data")

​
Advanced Configuration

​
Custom Metadata and Tags

You can add custom metadata and tags to your traces for better organization and filtering: 
import { MCPAgent, MCPClient } from 'mcp-use'

const agent = new MCPAgent({
  llm,
  client,
  maxSteps: 30
})

// Set metadata that will be attached to all traces
agent.setMetadata({
  agent_id: 'customer-support-agent-01',
  version: 'v2.0.0',
  environment: 'production',
  customer_id: 'cust_12345'
})

// Set tags for filtering and grouping
agent.setTags(['customer-support', 'high-priority', 'beta-feature'])

// Run your agent - metadata and tags are automatically included
const result = await agent.run("Process customer request")

​
Custom Callbacks

You can provide custom Langfuse callback handlers or other LangChain callbacks: 
import { CallbackHandler } from 'langfuse-langchain'
import { MCPAgent } from 'mcp-use'

// Create a custom Langfuse handler
const customHandler = new CallbackHandler({
  publicKey: 'pk-lf-custom',
  secretKey: 'sk-lf-custom',
  baseUrl: 'https://custom-langfuse.com'
})

const agent = new MCPAgent({
  llm,
  client,
  callbacks: [customHandler] // Use custom callbacks instead of auto-detected ones
})