BotArmor MCP server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BotArmor MCP server Check my agent on localhost:3000 with BotArmor."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
BotArmor MCP server
Crash-test your chatbot or AI agent from your AI assistant: Claude Code, Claude Desktop, ChatGPT, OpenAI Codex, Gemini CLI, Cursor, VS Code (Copilot) or Windsurf. Ask "test my agent with BotArmor" and BotArmor attacks the agent on up to 12 levels:
fake manager;
angry customer;
fake lawyer;
prompt injection;
role-play;
phishing;
AI disclosure under the EU AI Act;
invented facts;
and more.
Level 13 is added for agents with tools. The assistant gets back a report written for it: what broke, how badly, and the exact text to add to the agent's instructions. It can then edit your code and run the audit again.
It is a thin wrapper over the BotArmor API, the same one the Make app, the n8n node and the GitHub Action use.
How it works
You ask your assistant. For example: "Check the support agent in this repo with BotArmor."
The assistant calls
start_audit. It passes the agent's system prompt, which it reads from your code.Prompt mode (default): BotArmor plays that prompt on its own model. Use it for an agent on localhost or not deployed yet.
Live mode: BotArmor talks to your running bot at a public https URL. The assistant must first ask you to confirm you own the bot.
BotArmor attacks. For each level it runs 5 adaptive sessions. A judge model rules on each session, and a jury of three models confirms every break. An audit takes 5–20 minutes and uses one credit.
The assistant polls
get_audit_status. It shows progress: levels done out of total.It reads
get_audit_report. The report gives the grade A–F, a table of levels with severity, and for each failed level what happened plus a ready-to-paste fix for the system prompt.It proposes the fix in your code. With your OK it applies the fix, then runs
start_auditagain to check that the level now holds.
Your API key stays in your MCP client's configuration. The assistant never receives it. Prompts are not stored by BotArmor, only a SHA-256 fingerprint.
Related MCP server: ai-governance-controls
Get an API key
Create a key in the BotArmor dashboard, tab API. It starts with ba_live_. In the examples below, replace ba_live_xxx with it. Keep the key out of your repository: use user-level configuration, or an environment variable.
Connect your assistant
Claude Code
claude mcp add botarmor --scope user -e BOTARMOR_API_KEY=ba_live_xxx -- npx -y @botarmor/mcpCheck with claude mcp list, or /mcp inside a session.
Claude Desktop
Menu Settings → Developer → Edit Config opens claude_desktop_config.json:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Add the server, then fully quit and reopen Claude Desktop:
{
"mcpServers": {
"botarmor": {
"command": "npx",
"args": ["-y", "@botarmor/mcp"],
"env": { "BOTARMOR_API_KEY": "ba_live_xxx" }
}
}
}ChatGPT (web) and claude.ai: remote server, no install
Hosts that only connect to servers on the internet use BotArmor's hosted endpoint:
https://app.botarmor.eu/mcpAdd it as a custom MCP server or connector in your host. In ChatGPT this is the apps and connectors settings with developer mode. In claude.ai it is Settings → Connectors → Add custom connector. Menu names change often; look for "MCP server" or "custom connector".
The host opens a BotArmor page. Paste your API key there and click Connect.
The host receives its own token (OAuth 2.1 with PKCE). It never sees your API key.
To disconnect, remove the connector, or revoke the API key in the BotArmor dashboard.
The tools are the same four.
ChatGPT desktop app and OpenAI Codex (CLI and IDE)
They share one configuration. Use either the command line:
codex mcp add botarmor --env BOTARMOR_API_KEY=ba_live_xxx -- npx -y @botarmor/mcpor ~/.codex/config.toml:
[mcp_servers.botarmor]
command = "npx"
args = ["-y", "@botarmor/mcp"]
env = { BOTARMOR_API_KEY = "ba_live_xxx" }In the ChatGPT desktop app you can also add it under Settings → MCP servers → STDIO, with command npx, arguments -y @botarmor/mcp and the env variable.
Gemini CLI
gemini mcp add -s user -e BOTARMOR_API_KEY=ba_live_xxx botarmor npx -y @botarmor/mcpor ~/.gemini/settings.json:
{
"mcpServers": {
"botarmor": {
"command": "npx",
"args": ["-y", "@botarmor/mcp"],
"env": { "BOTARMOR_API_KEY": "$BOTARMOR_API_KEY" }
}
}
}$BOTARMOR_API_KEY is read from your shell environment, so the key is not written in the file. Check with /mcp in a session.
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"botarmor": {
"command": "npx",
"args": ["-y", "@botarmor/mcp"],
"env": { "BOTARMOR_API_KEY": "ba_live_xxx" }
}
}
}VS Code (GitHub Copilot agent mode)
Run MCP: Open User Configuration from the Command Palette and add the server. VS Code asks for the key once and stores it securely:
{
"inputs": [
{ "type": "promptString", "id": "botarmor-key", "description": "BotArmor API key (ba_live_...)", "password": true }
],
"servers": {
"botarmor": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@botarmor/mcp"],
"env": { "BOTARMOR_API_KEY": "${input:botarmor-key}" }
}
}
}Note that VS Code uses servers, not mcpServers.
Windsurf and other MCP clients
Any client that runs local MCP servers (stdio) works with the same three values:
command:
npxargs:
-y @botarmor/mcpenv:
BOTARMOR_API_KEY
In Windsurf, use the mcpServers block as for Cursor, in ~/.codeium/windsurf/mcp_config.json.
What to ask
"Check my agent on localhost:3000 with BotArmor." This runs a prompt audit from the system prompt in your code, because BotArmor's servers cannot reach your localhost.
"Audit our staging bot at https://staging.example.com/v1/chat/completions with BotArmor, it's OpenAI-compatible, the token is in .env." This runs a live audit; the assistant asks you to confirm you own the bot.
"Is the BotArmor audit done? Show me the report and fix the prompt."
"List my last BotArmor audits."
Tools
Tool | What it does |
| Starts an audit and returns its id ( |
| Status, progress (levels done out of total), and the grade once completed. |
| Grade, a table of levels with severity, and for each failed level what happened plus the text to paste into the system prompt. |
| Your latest audits. |
start_audit parameters:
system_prompt(required): the agent's instructions. For a live audit it is also the rulebook the judge checks answers against.target_type, one of:prompt: the default when no URL is given;openai-compatible: a chat-completions endpoint;webhook: any JSON endpoint.
endpoint_url: a public https URL, for live audits.headers: what the target needs. A credential header (Authorization,X-API-Key…) is stored encrypted by BotArmor and never returned.model: foropenai-compatible, the model name sent in the body.body_templateandresponse_path: forwebhook. The body uses{{input}},"{{history}}"or"{{messages}}"; the path points to the reply, e.g.data.reply.levels: a subset oflogic, toxic, hacker, lawyer, multilang, loop, roleplay, phishing, ethics, burst, disclosure, facts, agency.lang: the report language (fr,en,de,es,ru).min_grade: the pass threshold.authorization_confirmed: must betruefor a live audit. Set it only when you own the bot or hold the owner's written permission. BotArmor never tests third-party bots.
Errors you may see
"BotArmor rejected the API key": check
BOTARMOR_API_KEY."No audit credit left": buy a pack or upgrade in the dashboard.
"... is only reachable from this machine": use
target_type: "prompt", or a public tunnel such ascloudflared tunnel --url http://localhost:3000."the target bot did not answer": the live bot was down, or its URL or headers are wrong.
"An audit is already running": one audit at a time per account.
Develop
npm install
npm test # builds, then runs unit tests and an end-to-end stdio test against a mock APIBOTARMOR_API_URL points the server at another API base (default https://app.botarmor.eu/api/v1).
MIT licence. BotArmor AI is a brand of Rhone IA (Andrii Sydorenko EI), France. Reports are point-in-time test attestations, not certifications.
Available Tools
4 toolsget_audit_reportBotArmor audit reportARead-only
Findings of a completed BotArmor audit: grade, a table of levels with severity and breaks, and for every failed level what happened and the exact text to add to the agent's system prompt. Use it to propose the fix in the agent's code, then re-run start_audit to check.
Inputs: audit_id (required).
get_audit_statusBotArmor audit statusARead-only
Status and progress of a BotArmor audit (levels done out of total), and the grade once completed.
Inputs: audit_id (required).
list_auditsList BotArmor auditsARead-only
The user's latest BotArmor audits, newest first, with status, grade and score.
Inputs: limit.
start_auditStart a BotArmor auditA
Crash-test a chatbot or AI agent with BotArmor: up to 12 attack levels (fake manager, angry customer, fake lawyer, prompt injection, role-play, phishing, AI disclosure under the EU AI Act, invented facts...) plus level 13 for agents with tools, 5 adaptive sessions each. Two modes. target_type 'prompt' (default when no endpoint_url): BotArmor plays the agent's system prompt on its own model; use it for an agent running on localhost or not deployed yet, reading the system prompt from the code. target_type 'openai-compatible' or 'webhook': a live audit of a running bot at a public https URL; requires authorization_confirmed: true, only after the user confirmed they own the bot or have written permission. Returns the audit id; an audit takes 5 to 20 minutes, then use get_audit_status and get_audit_report. Uses one audit credit.
Inputs: system_prompt (required), lang, name, model, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a clearly distinct part of the audit lifecycle: starting an audit, checking status, retrieving findings, and listing past audits. The status vs. report distinction is well explained by their descriptions.
All tools use consistent snake_case with a clear verb_noun pattern: start_audit, get_audit_status, get_audit_report, list_audits. The get_audit_* pair and list_audits are predictable and readable.
Four tools are well-scoped for an audit workflow and each earns its place. This is neither thin nor bloated for the stated purpose.
The core lifecycle is covered: start, poll status, retrieve report, and list audits. Minor gaps such as cancelling an in-progress audit or deleting old audits are not present but are unlikely to block normal use.
Maintenance
Related MCP Connectors
MCP-native AI evaluation: rubric audits, eval suites, and proof reports for AI/LLM output.
Paid remote MCP for LLM security scans, jailbreak checks, analytics, checkout, and readiness.
Scan prompts for injection attacks, redact PII, and audit LLM SDK usage from any MCP client
Real-time prompt injection filtering, MCP payload inspection, and A2A trust scoring.
Related MCP Servers
AlicenseCqualityDmaintenanceIntegrates AI safety analysis, red-teaming, and prompt auditing directly into MCP-compatible clients like Claude Desktop and Cursor IDE, allowing real-time analysis of prompts and detection of jailbreak attempts.284Apache 2.0- AlicenseAqualityCmaintenanceProvides AI governance controls as MCP tools for safety screening, risk classification, and red teaming of AI systems, returning structured governance reports.32Apache 2.0
- AlicenseAqualityDmaintenanceProvides prompt injection detection, PII/secrets redaction, and an audit trail for AI agents via MCP tools.4MIT
- AlicenseBqualityDmaintenanceEnables MCP clients to audit AI search visibility, generate intent-aligned social content, and assess Agentic Commerce Readiness with remediation files.3MIT