# Geetest MCP

> Geetest MCP is an API wrapper for advanced anti-bot CAPTCHA protection (v4). It lets your agent validate user tokens, assess risk based on IP and behavior patterns, and manage site policies entirely through natural conversation. You can monitor detailed validation statistics, view blocked IPs, and configure security thresholds without ever leaving your chat interface.

## Overview
- **Category:** security
- **Price:** Free
- **Tags:** geetest, captcha, anti-bot, risk-assessment, bot-detection

## Description

Stop manually checking logs or juggling multiple dashboards just to know if a bot hit your form. This MCP lets you run Geetest's powerful anti-bot checks right through your AI agent. You can validate user tokens immediately after submission, but it goes deeper than that: the system evaluates the user’s entire behavior pattern and IP history for risk. Need to adjust how strict the CAPTCHA is? You can modify policies on the fly. The whole process—from checking if a token passed to tracking down suspicious IPs and viewing statistical trends—is handled via conversation, which means you never have to leave your workflow. If you're looking for enterprise security tools connected to AI agents, Vinkius hosts this MCP alongside thousands of others so you can connect everything in one place.

## Tools

### get_blocked_ips
Retrieves a list of IP addresses that the CAPTCHA system has blocked due to suspicious activity or failures.

### get_captcha_config
Fetches the current settings and configuration details for the CAPTCHA widget, useful for debugging frontend setup.

### get_validation_stats
Gathers key metrics on CAPTCHA usage, showing total attempts and pass/fail rates to identify attack patterns.

### set_policy
Allows immediate configuration changes, such as adjusting risk thresholds or setting new validation rules for the system.

### validate_captcha
Checks a user's CAPTCHA submission using required tokens to confirm basic human completion status.

### validate_with_risk
Performs the most accurate check by analyzing both the CAPTCHA result and detailed user behavior patterns for bot signs.

## Prompt Examples

**Prompt:** 
```
Validate this CAPTCHA: lot_number=abc123, pass_token=xyz789
```

**Response:** 
```
✅ CAPTCHA validation PASSED! Risk level: low. User behavior verified as human.
```

**Prompt:** 
```
Show me today's validation statistics.
```

**Response:** 
```
📊 Today's stats: 1,250 total attempts, 1,180 passed (94.4%), 70 blocked (5.6%). Normal traffic pattern detected.
```

**Prompt:** 
```
Show me all blocked IPs from the CAPTCHA system.
```

**Response:** 
```
🚫 2 IPs currently blocked: 1.2.3.4 (15 failed attempts), 5.6.7.8 (8 failed attempts).
```

## Capabilities

### Validate CAPTCHA responses
Submit a user-provided token and let the system confirm if the CAPTCHA passed validation.

### Assess risk level
Run a deeper analysis that combines the CAPTCHA result with observed user behavior to score potential bot activity.

### Manage security policies
Change validation modes, set risk thresholds, or update IP whitelists without touching any configuration files.

### Review blocked IPs
Retrieve a list of IP addresses that the system automatically flagged and blocked due to repeated failure attempts.

### Check validation statistics
Get usage metrics, including total attempts, passed counts, and identified attack patterns over time.

## Use Cases

### The form conversion rate dropped sharply after launch.
A Product Manager asks their agent: 'Check get_validation_stats for the last 24 hours.' The agent reports a massive spike in failed attempts, pointing to an obvious bot attack. They then use validate_with_risk on sample tokens to confirm the risk level and advise changing policies using set_policy.

### A competitor found an IP range that bypasses basic CAPTCHA.
The Security Engineer runs get_blocked_ips, seeing a pattern of failed attempts coming from a specific subnet. They then use set_policy to block the entire range and run validate_captcha on a test token to ensure the patch didn't break legitimate traffic.

### The development team needs to debug a frontend integration issue.
A developer uses get_captcha_config first. When that looks correct, they use validate_captcha with specific lot and pass tokens to confirm the basic communication flow between the client widget and the server is working.

### Need to restrict access after a major security incident.
The Security Engineer uses set_policy to temporarily increase the required risk score for all forms. They then monitor get_validation_stats immediately afterward, ensuring that only truly high-risk activity is being flagged.

## Benefits

- Better visibility into attacks: Use get_validation_stats to see exactly when and how bot traffic spikes, allowing you to pinpoint weaknesses in your forms.
- Tighter security without downtime: Run validate_with_risk for a deep behavioral check. This is much stronger than basic CAPTCHA validation and minimizes false positives on legitimate users.
- Immediate policy control: Need the system to be stricter right now? Use set_policy to change risk thresholds or whitelists instantly, all through your agent chat.
- Audit blocked activity: Quickly check get_blocked_ips when suspicious behavior is reported. You don't have to dig through server logs for IP details anymore.
- Easy setup verification: Run get_captcha_config anytime to confirm that the frontend widget settings match what you expect, saving hours of dev time.

## How It Works

The bottom line is that instead of calling an API endpoint directly, your agent performs complex security operations through simple natural language requests.

1. Subscribe to this MCP and input your unique Geetest Captcha ID and Private Key.
2. Tell your agent the task: for example, 'Check if user XYZ is safe.'
3. The system runs checks—like validating the token or running a risk assessment—and gives you a clear pass/fail status.

## Frequently Asked Questions

**How do I check if my CAPTCHA integration is set up correctly using get_captcha_config?**
Use get_captcha_config to retrieve the current live settings for your widget. This confirms that the parameters shown in the MCP match what your frontend developers intended, saving you time debugging mismatched keys.

**Is validate_with_risk better than validate_captcha?**
Yes. While validate_captcha only checks if a user completed the visual puzzle, validate_with_risk also analyzes behavior patterns and IP history for signs of automation, making it significantly more reliable.

**What if I need to change my bot detection rules quickly?**
Use set_policy. This tool allows you to modify critical security settings—like risk thresholds or whitelists—immediately through your agent conversation, without needing a code deployment.

**Can I check which IPs were blocked by the system?**
Yes, run get_blocked_ips. This tool provides a clean list of every IP address flagged and blocked by Geetest, helping you investigate attack sources or false positives.

**What does the output from get_validation_stats tell me about overall bot attack patterns?**
The statistics break down total attempts versus passed or blocked counts. This allows you to monitor if your block rate is abnormal, helping security teams identify potential shifts in attack frequency.

**When I call set_policy, how quickly do those changes take effect for my users?**
The policy updates are immediate. When the API confirms a change, it means the new validation modes and risk thresholds apply right away; there's no waiting period or redeployment needed.

**If my frontend sends incomplete parameters, how does validate_captcha handle the error?**
The tool expects specific inputs like lot number, pass token, and generation time. If you send missing or malformed data, the API returns an explicit failure code detailing exactly which required parameter is causing the issue.

**For validate_with_risk, what specific behavioral pattern data does the API need to analyze user behavior effectively?**
This validation requires context beyond simple tokens. You must provide detailed information on the user's IP and interaction history, letting the system build a comprehensive profile of their activity.

**How do I get my Geetest Captcha ID and Private Key?**
Sign up at [Geetest Console](https://www.geetest.com/), create a new CAPTCHA project, and find your Captcha ID and Private Key in the project settings.

**What's the difference between validate_captcha and validate_with_risk?**
validate_captcha checks only the CAPTCHA completion. validate_with_risk also analyzes the user's IP address and behavior patterns for more accurate bot detection.

**How does Geetest detect bots?**
Geetest v4 uses behavioral analysis, mouse movement patterns, touch events, and environmental fingerprints to distinguish humans from automated scripts — without requiring users to solve puzzles.