# UserStack User-Agent Lookup MCP

> UserStack User-Agent Lookup. This MCP server parses raw User-Agent strings, instantly identifying device type, operating system, browser version, and brand from any client request. Your AI agent gets structured data about who's making the call—whether it’s a desktop Chrome user or a Googlebot crawler.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** user-agent, device-detection, browser-parsing, web-analytics, bot-detection

## Description

When your AI agent runs into messy web traffic logs, it doesn't know what to do with raw User-Agent strings. That’s where the **UserStack User-Agent Lookup** server steps in. It uses a single tool, `detect_user_agent`, to instantly turn that jumble of text into structured data your agent can actually use. This isn't just reading a string; it’s parsing complex client requests to figure out exactly who's making the call—whether it’s a human browsing on an iPhone or some automated search crawler.

Your AI agent gets granular details about the requesting device. The `detect_user_agent` tool first classifies the entire platform, telling you immediately if the request came from a **mobile phone**, a **desktop computer**, or a **tablet**. It handles the subtle differences between these categories so your agent knows how to adjust its behavior accordingly.

It pulls out deep technical details about the client's software. You’ll get the specific operating system—be it macOS, Windows, Android, or iOS—along with the full browser version number used by the client. This is crucial; knowing if a user is on Chrome 120 versus Chrome 123 changes how your agent needs to format outgoing requests.

Beyond just OS and browser versions, the server identifies the manufacturer's name. It reads the string to provide the brand data for the device, giving you names like Apple or Samsung. This level of detail helps your agent profile user hardware reliably.

The tool also checks if a request is coming from a known automated source. It detects whether the call originates from a human user or an established search engine bot, such as Googlebot. Your agent gets clear binary data on this front: human interaction versus programmatic scraping. This capability helps you differentiate between real-world usage and algorithmic polling.

The entire process revolves around taking that messy User-Agent string—the raw input—and converting it into clean, usable parameters for your agent to consume. The `detect_user_agent` tool doesn't just guess; it systematically structures the data points. It takes all the disparate pieces of information—platform type, OS version, browser name, device brand, and bot status—and packages them together in a format your AI client can process instantly.

If you’re auditing web traffic patterns or building personalized user experiences, this is what happens: Your agent sends the raw User-Agent string to `detect_user_agent`. The tool runs its parsing logic, returning structured fields. You immediately know if the request was initiated by a desktop Chrome user running Windows 11, or maybe an Apple Safari browser on an iPadOS device. It doesn't leave anything vague; it gives you specific versions and brands.

This detailed breakdown lets your agent act like a dedicated network analyst when reviewing logs. Instead of just seeing 'browser detected,' the agent sees 'Chrome vX.Y running on Windows 10.' This specificity allows developers to write highly targeted code paths or adjust data models based on precise client environments. It's robust enough that if you feed it an unusual combination—say, a niche embedded device browser—it still provides the best classification possible across all known metrics.

It’s essential for debugging where platform-specific bugs are hiding, and for building APIs that need to behave differently depending on whether they detect Googlebot or a user with specific mobile hardware. The `detect_user_agent` tool handles this complex differentiation instantly, ensuring your agent's actions are always informed by the precise client context.

## Tools

### detect_user_agent
Parses a User-Agent string and returns structured data identifying the device, operating system, browser version, and bot status.

## Prompt Examples

**Prompt:** 
```
Detect this User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36
```

**Response:** 
```
Parsing User-Agent... I've identified this as a Desktop user on Windows 10 using Google Chrome version 91. It is not a search engine crawler.
```

**Prompt:** 
```
Is this a bot? 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)'
```

**Response:** 
```
Checking agent... Yes, this is identified as Googlebot version 2.1, a verified search engine crawler from Google.
```

**Prompt:** 
```
Identify the device brand for this UA: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.1 Mobile/15E148 Safari/604.1'
```

**Response:** 
```
Analyzing... This User-Agent belongs to an Apple iPhone running iOS 14.6. The browser is Safari mobile version 14.1.1.
```

## Capabilities

### Classify client platform
The tool determines if the request originates from a mobile phone, desktop, or tablet.

### Extract OS and browser details
It pulls out the specific operating system (like macOS or Windows) and the full browser version used by the client.

### Identify device brand
The server reads the string to provide the manufacturer's name, such as Apple or Samsung.

### Detect automated crawlers
It checks if a request is from a known search engine bot (like Googlebot) versus a human user.

### Structure raw data
The tool takes the messy User-Agent string and converts it into clean, usable parameters for your agent to process.

## Use Cases

### Debugging a Cross-Browser Bug
A developer notices an error only occurs sometimes. They pass the questionable User-Agent string to their agent. The agent uses `detect_user_agent` and reports: 'This is Safari mobile, version 14.1.1.' Now the dev knows exactly which corner case they need to fix.

### Filtering Bot Traffic
A site gets flooded with junk traffic from scrapers. Instead of blocking everything, the ops team prompts their agent with a batch of User-Agents. The agent runs `detect_user_agent` on each one and returns only the IPs linked to confirmed human browsers.

### Personalizing Content Streams
A digital marketer wants to show different content based on screen size. They pipe the incoming request UA through their agent, which runs `detect_user_agent`. If the result is 'mobile', the agent serves a simplified version of the page.

### Verifying Client Capabilities
A legacy system needs to know if the client supports modern APIs. The developer uses `detect_user_agent` to check for specific OS markers, ensuring they don't waste time building features that half their user base can't run.

## Benefits

- **Structured Data:** Instead of reading paragraphs of text, your agent gets clean parameters. You can immediately use the output to gate functionality—for example, showing a specific layout only if `detect_user_agent` confirms the client is 'mobile'.
- **Bot Differentiation:** Need to know if traffic is real? Running `detect_user_agent` tells you instantly if the request comes from Googlebot or a human. This lets your agent skip processing known scrapers and focus on actual users.
- **OS Compatibility Checks:** Debugging across platforms is tough. The tool provides precise OS information (e.g., 'Windows 10' vs 'macOS Monterey'), letting you build logic that only runs if the client meets specific environmental requirements.
- **Device Profiling:** You can figure out exactly what hardware a visitor uses—is it an iPhone, a Samsung tablet, or an old desktop? This level of detail is critical for targeted marketing and UX design.
- **Efficiency in Auditing:** It moves technical auditing from manual log searching to natural conversation. Your agent does the heavy lifting, giving you instant verification on client capabilities.

## How It Works

The bottom line is: you feed it a raw User-Agent string, and it spits out structured facts about what kind of machine sent the request.

1. Subscribe to this server and get your UserStack Access Key from userstack.com.
2. Input the raw User-Agent string directly into your AI client's prompt or workflow.
3. Your agent calls the `detect_user_agent` tool, which returns clean JSON data detailing the device, OS, browser, and bot status.

## Frequently Asked Questions

**How does UserStack User-Agent Lookup MCP Server detect if I'm running on mobile?**
The `detect_user_agent` tool classifies the client platform into Mobile, Desktop, or Tablet. This classification is based on known device signatures within the raw string.

**Can UserStack User-Agent Lookup MCP Server tell me if traffic is from a bot?**
Yes. The tool checks the UA against known patterns and reports whether the source is a verified search engine crawler (like Googlebot) or likely human activity.

**What information does `detect_user_agent` return about my browser?**
`detect_user_agent` returns the full browser version number and name. For example, it can distinguish between Chrome 91 and Chrome 92.

**Does UserStack User-Agent Lookup MCP Server work with all AI clients?**
Yes, because it uses the Model Context Protocol (MCP), any compatible AI client—Claude, Cursor, VS Code, etc.—can connect to and use this server's tools.

**How do I authenticate when running the `detect_user_agent` tool?**
You must use your dedicated UserStack Access Key for authentication. You provide this key to your AI client or environment variable, which allows the MCP server access. Never hardcode this key; always manage it securely through your deployment system.

**What happens if I pass malformed data to `detect_user_agent`?**
The tool is built for robustness and will not fail on garbage input. It parses what information it can extract from the string, returning structured data fields where possible. This means even incomplete User-Agents give you partial context.

**Are there rate limits when calling `detect_user_agent`?**
Yes, usage is governed by your subscription tier and plan limits. High-volume users should monitor their request counts to avoid throttling. The MCP server will provide standard rate limit error codes if you hit a cap.

**Can `detect_user_agent` help me debug OS compatibility issues?**
Absolutely. It provides detailed operating system and device profiles, letting you know exactly which version of Windows or macOS the request came from. This helps you target specific CSS rules or JavaScript functionality for precise debugging.

**Can I identify if a user is on an iPhone?**
Yes! Use the `detect_user_agent` tool. The response will include the device brand ('Apple') and the specific model or type if available in the UA string.

**Does this server detect search engine bots?**
Yes. The underlying API identifies known crawlers like Googlebot or Bingbot. The agent will explicitly state if the detected agent is a crawler.

**Can I parse multiple User-Agents at once?**
Currently, the `detect_user_agent` tool processes one string per call. You can ask your AI agent to perform sequential checks for a list of strings.