# Papertrail MCP

> Papertrail connects your AI client directly to real-time cloud logs, letting you search millions of events and manage entire log infrastructure via natural conversation. You can list all connected systems, create custom log groups for specific services, or check event history—all without touching a dashboard. It’s pure command-line visibility for modern DevOps.

## Overview
- **Category:** devops-cicd
- **Price:** Free
- **Tags:** logging, real-time-logs, cloud-monitoring, event-search, syslog

## Description

You connect your AI agent right here when you need instant visibility into cloud logs and real-time troubleshooting, all without touching a dashboard. This server lets your client interact with the core functions of log management using pure conversation. You'll use it to search massive event databases, track which systems are sending data, structure your log sources, and control where that data ends up.

To start, when you need to find something specific—whether it’s a bug from last night or an error happening right now—you run `search_events`. This tool lets your agent search through millions of historical or live log entries using complex query syntax. You can pull back all matching events across defined time ranges, and it handles pagination for you if the results are huge. If you need to watch logs as they come in, it tails real-time data streams directly into your chat interface.

Need to know what's reporting? Use `list_systems`. This tool gives you a clean list of every unique system ID that’s currently configured to send logs into Papertrail. It keeps you in the loop on which services are active and sending data, so you never wonder if something important is falling through the cracks.

When your infrastructure gets complex, you gotta organize it. You use `list_groups` to see every existing organizational log group that contains systems. Then, if a new service pops up or you need to separate staging from production logs, you run `create_group`. This establishes a clean, logical boundary—a dedicated log group—that keeps related systems and their logs together for easy filtering later on.

Managing where your data goes is just as important. You check what's available by calling `list_destinations`, which retrieves every configured endpoint for archiving or forwarding data in the account. If you need to send those logs somewhere else—say, a dedicated compliance bucket—you use `create_destination`. This sets up a new, defined endpoint so your log data gets archived or forwarded exactly where it needs to go.

When you combine these tools, you're talking pure DevOps visibility through natural conversation. You don't gotta touch a single dashboard. Your agent first uses `list_systems` to verify the sources. Then, if necessary, it runs `create_group` to organize them into a specific log group. When you’re ready for an answer, it executes `search_events`, letting you drill down using powerful query syntax against that organized data set. The entire process—from checking system status to querying historical events and setting up new archival sinks—runs entirely through your AI client's conversation with these tools.

## Tools

### create_destination
Creates a new defined endpoint for archiving or forwarding log data.

### create_group
Establishes a new organizational boundary (log group) to contain related systems and logs.

### list_destinations
Retrieves a list of all configured log destinations for the account.

### list_groups
Lists every existing organizational log group that contains systems.

### search_events
Searches through the log event database using complex query syntax, returning relevant historical or real-time entries.

### list_systems
Retrieves a list of all individual services and systems currently sending logs to Papertrail.

## Prompt Examples

**Prompt:** 
```
List all systems sending logs to my Papertrail account.
```

**Response:** 
```
I've retrieved your systems. You have 3 active systems: 'web-prod-01' (ID: 101), 'db-master' (ID: 102), and 'api-gateway' (ID: 103).
```

**Prompt:** 
```
Search for 'ConnectionTimeout' in the logs.
```

**Response:** 
```
Searching events... I found 12 occurrences of 'ConnectionTimeout' in the last hour. Most are coming from 'api-gateway'. Would you like to see the full log entries?
```

**Prompt:** 
```
Create a new log group called 'Critical-Services' for systems 101 and 103.
```

**Response:** 
```
Successfully created the log group 'Critical-Services' (ID: 505) containing systems 101 and 103. You can now filter searches specifically for this group.
```

## Capabilities

### Search Log Events
Your AI agent searches through millions of log entries using specific syntax, retrieving all matching events.

### Identify Active Systems
The server lists every unique system ID that is currently configured to send logs into Papertrail.

### Organize Log Sources
You can create and list log groups, allowing you to logically separate different parts of your infrastructure for easier filtering.

### Manage Data Sinks
The agent allows you to view existing or set up new destinations to control where logs are archived or forwarded.

## Use Cases

### Debugging a Cascading Failure
The main service starts failing intermittently. Instead of jumping between dashboards, you tell your agent: 'Check logs from `web-prod` and `api-gateway` for database connection errors.' The agent uses `search_events`, filtering by system IDs found via `list_systems`, and returns the exact stack trace, solving the problem immediately.

### Auditing Compliance Data
You need to prove that all customer data sources are logged correctly. You run `list_groups` first to verify every required system is represented, then use `search_events` with date range filters to pull a comprehensive audit trail for compliance review.

### Onboarding New Services
A new microservice (ID: 104) gets added. You run `list_systems`, confirm its presence, and then use the agent to create a dedicated log group (`create_group`) called 'New-Service-104'. This keeps the main view clean while ensuring visibility.

### Data Retention Policy Enforcement
The company mandates that all security logs must be archived for 7 years. You use `list_destinations` to check the current setup, and then guide your agent to configure a new destination (`create_destination`) specifically for long-term compliance storage.

## Benefits

- Pinpoint failures instantly: Instead of scrolling through raw data, you can use `search_events` to target specific error codes or user IDs across millions of records. It cuts down troubleshooting time from minutes to seconds.
- Keep your logs clean and separated: Use the `create_group` tool to build logical boundaries (e.g., 'Payments Service v2'). This prevents critical production errors from getting buried under noisy staging logs.
- Maintain full system visibility: The `list_systems` tool gives you a single, reliable inventory of every service logging data. You never have to wonder if an important component dropped out of the monitoring picture.
- Control your data flow: With tools like `create_destination`, you manage exactly where logs are going—whether they get archived long-term or simply discarded after a set period. This is crucial for compliance.
- Operational simplicity: You don't need to learn Papertrail's proprietary UI deep dives. Just tell your agent, 'What's wrong with the API gateway?' and it runs the necessary checks using multiple tools in sequence.

## How It Works

The bottom line is: you manage your entire logging stack—from organization to retrieval—using natural language commands, bypassing manual dashboards entirely.

1. Subscribe the server and input your Papertrail API Token.
2. Instruct your AI client (e.g., 'Show me all systems that reported errors in the last hour.')
3. The agent runs the necessary tool calls (`list_systems` then `search_events`) and delivers the results directly into the conversation thread.

## Frequently Asked Questions

**How do I find an error from a specific service using the Papertrail MCP Server?**
You use `search_events`. First, run `list_systems` to get the exact system ID. Then, structure your search query to include that ID and the specific error pattern you're looking for.

**Can I manage log groups using the Papertrail MCP Server?**
Yes. You use `list_groups` to see what exists, then run `create_group` if you need a new boundary—like separating all 'Payments' logs from everything else.

**What is the difference between list_systems and list_groups?**
`list_systems` gives you an inventory of individual sources (e.g., 'web-prod-01'). `list_groups` shows your high-level containers that hold those systems together (e.g., 'Production Environment').

**Do I need to use the Papertrail MCP Server for data archiving?**
Not necessarily, but you can manage it. Use `list_destinations` and `create_destination` to control where your logs go—whether they get archived or streamed elsewhere.

**What happens if I don't provide credentials when running `search_events`?**
The server rejects the request immediately. You must supply a valid Papertrail API token for any log query to work. Always check your connection settings before trying complex searches.

**How do I manage log routing and archiving using `create_destination`?**
The tool establishes an output endpoint, telling the system where to send logs. After running `list_destinations`, you can use `create_destination` to point data toward external storage or a secondary service.

**Does using `list_groups` help me filter my subsequent searches with `search_events`?**
Yes. By listing groups, you get the specific identifiers needed for filtering. This lets your AI agent scope the search results to only include logs from that defined group.

**Are there time constraints or limits when running `search_events`?**
While Papertrail handles millions of events, every API call has a rate limit. For extremely large searches, the system manages pagination and live tailing automatically to prevent timeouts.

**Can I search for specific error messages across all my logs?**
Yes! Use the `search_events` tool with the `q` parameter. You can use Papertrail's search syntax (e.g., 'error OR critical') to filter events across your systems.

**How do I see which servers or applications are currently sending logs?**
Simply run the `list_systems` tool. It will return a list of all systems configured in your Papertrail account, including their names and IDs.

**Can I create a new group to organize specific systems?**
Yes, use the `create_group` tool. You can provide a name and a comma-separated list of system IDs to group them together for easier monitoring.