Secure, observe, and reliably test Model Context Protocol (MCP) deployments and AI agents

⭐ If Kurral saves you hours (or dollars), please star the repo — it helps a lot!

• Testing or upgrading agents → Deterministic Agent Testing ✅ Available Now
• Want a hands-on demo in <5 minutes → Project Generator ✅ Available Now
• Interested in MCP security/observability → Join Early Access Program 🚧 Q1 2026

Kurral is a powerful open-source testing and replay framework that brings control and reliability to AI agent development. Kurral is framework-agnostic and operates at the execution and protocol layer. LangChain support is provided as a convenience, not a requirement.

Model Context Protocol (MCP) is rapidly becoming the standard for AI agent tool integration — adopted by Anthropic, OpenAI, Google, Microsoft and others. Yet enterprises face critical hurdles before full adoption:

• 🔍 Visibility – What tools are agents calling? What data is flowing?
• 🛡️ Security – Are MCP servers vulnerable to tool poisoning, prompt injection, or data exfiltration?
• 🧪 Reliable Testing – How to test agents deterministically without unpredictable outputs or massive API costs?

Kurral addresses all three: deterministic testing available now, MCP observability and security testing coming Q1 2026.

MCP Proxy with complete traffic visibility and deterministic replay

Kurral will sit between agents and MCP servers, capturing execution, traffic, and side effects without requiring changes to MCP implementations.

Planned Capabilities:

• Capture & replay all MCP tool calls with full SSE streaming
• Performance metrics (duration, TTFE, event rates)
• Multi-server routing & semantic tool matching
• Shareable .kurral artifacts for debugging

Use Cases: Production issue reproduction, cost-free development, team collaboration.

Email [email protected] with subject "MCP Early Access" to join the waitlist.

Deterministic Replay for regression testing and A/B comparison

from kurral import trace_agent, trace_agent_invoke

@trace_agent()
def main():
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent_executor = AgentExecutor(agent=agent, tools=tools)

    result = trace_agent_invoke(agent_executor, {"input": user_input}, llm=llm)
    return result

Deterministic Replay:

• A Replay (Deterministic): High config similarity → cached outputs, zero API cost
• B Replay (Exploratory): Changes detected → re-execute LLM with semantic tool caching

Agent Regression Score (ARS):

ARS = (Output Similarity × 0.7) + (Tool Accuracy × 0.3)

Penalties for new/unused tools. Perfect for CI/CD thresholds.

Side Effect Protection: Auto-generates config, requires manual review before replay.

Use Cases:

• ✅ Regression testing & CI/CD
• ✅ Model upgrades (GPT-4o vs. newer models)
• ✅ Prompt engineering comparisons
• ✅ 99% API cost reduction in testing

📖 Deep Dive: How Replay Works →

Automated testing against the SAFE-MCP threat framework

All security testing is built on top of Kurral's capture and replay system, allowing attacks to be reproduced, compared, and audited deterministically.

Kurral will systematically test deployments against critical MCP attacks:

Phase 1 (Q1 2026):

• ✅ T1001 Tool Poisoning
• ✅ T1102 Prompt Injection
• ✅ T1201 MCP Rug Pull
• ✅ Cross-Tool Shadowing
• ✅ Data Exfiltration
• ✅ Unauthorized Tool Execution
• ✅ Malicious Server Distribution

kurral security test baseline.kurral --techniques T1001,T1102

Deliverables:

• 50–70 attack variants tested
• Detailed PDF/JSON reports with severity, findings & remediation
• Baseline vs. attack comparison

📖 Security Roadmap & Details →

pip install kurral                # Deterministic testing & replay

From source:

git clone https://github.com/Kurral/Kurralv3.git
cd Kurralv3
pip install -e "."

Note: MCP proxy features are coming in Q1 2026. Current release (v0.4.0) includes deterministic agent testing and project generator.

MCP proxy features are currently in development. Expected Q1 2026.

Planned workflow:

kurral mcp init                     # Generate config
kurral mcp start --mode record      # Proxy runs on localhost:3100
# Point your agent to http://localhost:3100
kurral mcp export -o session.kurral
kurral mcp start --mode replay --artifact session.kurral

Email [email protected] to get early access when available.

from kurral import trace_agent, trace_agent_invoke

@trace_agent()
def main():
    # Your agent setup...
    result = trace_agent_invoke(agent_executor, {"input": user_input}, llm=llm)
    print(result['output'])

Run → artifact saved automatically.

First replay triggers auto-generation of side_effect/side_effects.yaml with smart suggestions. Review and set done: true.

Then replay:

kurral replay --latest
# or
kurral replay <kurral_id>

Detailed output includes replay type, ARS score, cache hits, and changes detected.

📖 Deep Dive: Replay System →

Generate a production-ready agent in seconds:

# Create new agent project (vanilla Python - framework-free)
kurral init my-agent

# Or use LangChain framework
kurral init my-agent --framework langchain

# What you get:
# ✅ Complete agent with 3 production tools
# ✅ Kurral integration (2 decorators)
# ✅ Test suite with replay
# ✅ Full documentation

Templates are reference agent implementations, not framework requirements. They demonstrate correct Kurral integration patterns and are intended to be modified or replaced.

Included Tools:

• web_search - Internet search (Tavily)
• calculator - Safe math evaluation (deterministic!)
• read_file - Secure file reading

Explore Examples: Check out /examples for three complete production examples:

• Customer Support Agent (FAQ + web search)
• Code Review Agent (security + style checks)
• Research Assistant (multi-step reasoning)

Each example includes cost analysis showing 75-98% savings with Kurral replay!

Local (default) → artifacts/ and replay_runs/

Cloud (R2/S3-compatible) → scalable, team-shared artifacts

from kurral import configure

configure(
    storage_backend="r2",
    r2_account_id="...",
    r2_bucket_name="kurral-artifacts"
)

Customer shares .kurral artifact → You replay exact session locally → See exactly what they saw

Capture golden path → Run tests against artifact → Fail build if ARS < 0.8 → Zero API costs

Run baseline with GPT-4 → Change to GPT-4.5 → Replay with new model → Get quantitative ARS comparison

100 test runs/day without Kurral: $50/day = $1,000/month With Kurral (record once, replay 99 times): $0.50/day = $10/month Savings: $990/month (99% reduction)

• ✅ Now (v0.4.0): Deterministic agent testing, project generator, replay system
• 🚧 Q1 2026: MCP observability proxy + Phase 1 security testing (7 critical threats)
• 🔮 Q2 2026+: Full SAFE-MCP coverage, policy engine, continuous monitoring

📖 Security Roadmap →

• MCP proxy and observability features not yet released (Q1 2026)
• Security testing in active development (Q1 2026)
• ReAct & LCEL agents fully supported (LangGraph streaming coming soon)
• Vision inputs not yet captured

Core Components (Available Now):

• trace_agent - Decorator for agent main function
• trace_agent_invoke - Wrapper for capturing traces
• replay - Replay engine with A/B detection
• ars_scorer - Agent Regression Score calculation
• side_effect_config - Side effect management

MCP Components (Coming Q1 2026):

• KurralMCPProxy - FastAPI HTTP/SSE MCP Proxy
• MCPCaptureEngine - Traffic capture to .kurral artifacts
• MCPReplayEngine - Cached response replay
• MCPRouter - Multi-server routing

📖 Detailed Architecture →

• Discord: https://discord.gg/pan6GRRV
• Issues: github.com/Kurral/Kurralv3/issues
• Email: [email protected]

Contributions welcome — fork, branch, PR!

Apache 2.0 - see LICENSE for details.

MCP is becoming the standard for AI tool integration. As adoption accelerates, enterprises need:

1. Visibility into what tools agents are calling
2. Security assurance that MCP servers aren't compromised
3. Testing capabilities that don't require expensive API calls

Kurral provides all three in one platform.

Built for the MCP community. If this solves a problem for you, please star the repo and join our Discord!

Ready to test your AI agents with deterministic replay?
pip install kurral
MCP observability coming Q1 2026