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.
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.
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_audit again 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
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.
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.
Menu Settings → Developer → Edit Config opens claude_desktop_config.json:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/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" }
}
}
}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.
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 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/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" }
}
}
}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.
Any client that runs local MCP servers (stdio) works with the same three values:
command: npx
args: -y @botarmor/mcp
env: BOTARMOR_API_KEY
In Windsurf, use the mcpServers block as for Cursor, in ~/.codeium/windsurf/mcp_config.json.
"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."
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: for openai-compatible, the model name sent in the body.
body_template and response_path: for webhook. The body uses {{input}}, "{{history}}" or "{{messages}}"; the path points to the reply, e.g. data.reply.
levels: a subset of logic, 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 be true for a live audit. Set it only when you own the bot or hold the owner's written permission. BotArmor never tests third-party bots.
"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 as cloudflared 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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| audit_id | Yes | Audit id, e.g. BA-7NRZ26D4 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, so the description is free to add value — and it does, enumerating the report's internal structure and disclosing that it only yields findings for a completed audit. It omits error behavior for a not-yet-complete or invalid audit id, which would have been the last useful detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first front-loads what the agent receives, the second tells it what to do with the result. No filler, no restating of the tool name or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and largely discharges it by naming the grade, levels table, and per-failure prompt text. The remaining gap is failure modes — what an agent gets for a non-existent or incomplete audit — which matters for a lookup keyed on an external id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single audit_id parameter carries a format pattern and a worked example (BA-7NRZ26D4), so the schema does the heavy lifting. The description adds nothing about the identifier beyond the word 'completed', so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states precisely what the tool returns — grade, a levels table with severity and breaks, and per-failed-level details plus prompt text — and scopes it to a 'completed' audit, which separates it from get_audit_status and list_audits by implication. It never uses an explicit retrieval verb and doesn't name those two siblings, so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use it to propose the fix in the agent's code, then re-run start_audit to check' gives a concrete downstream workflow and names the sibling to call afterwards. The 'completed' qualifier implies when it applies, but the description never explicitly contrasts it with get_audit_status for in-progress audits or says what happens if the audit isn't finished.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status and progress of a BotArmor audit (levels done out of total), and the grade once completed.
| Name | Required | Description | Default |
|---|---|---|---|
| audit_id | Yes | Audit id, e.g. BA-7NRZ26D4 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety. The description adds useful behavioral context about what the response contains: levels completed out of total and the grade once completed, which helps the agent understand state progression.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with zero wasted words. The purpose and return progression are front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description still explains the shape of the return value (progress and final grade). It does not mention error conditions, polling behavior, or how long audits take, which would be useful but are not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single audit_id parameter is fully documented with a pattern and example. The description adds no additional parameter meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (a BotArmor audit) and what it returns (status, progress, and final grade). It implicitly contrasts with get_audit_report and list_audits by focusing on progress rather than the report itself or a list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: polling an audit after starting it or checking progress until completion. It does not explicitly say when to use this instead of get_audit_report or list_audits, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's latest BotArmor audits, newest first, with status, grade and score.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many, default 10. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is the ordering guarantee ('newest first') and the fields present on each item. It does not say what 'latest' means in scope (e.g. per-workspace, all-time) or whether results are truncated beyond the limit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with the resource and scope, followed by ordering and return fields. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description helpfully enumerates the salient returned fields (status, grade, score) and ordering, which is enough to call the tool correctly. A brief note distinguishing it from get_audit_report would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single limit parameter is documented at 100% schema coverage including its default and bounds, so the schema carries the burden. The description adds nothing about the limit, not even how the default of 10 interacts with 'latest'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific resource (BotArmor audits), the scope (the user's latest) and the ordering (newest first), plus the key fields returned (status, grade, score). It is clear what the tool does, but it never mentions the sibling tools (get_audit_status, get_audit_report) that overlap with the 'status/grade' data it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the browse/discovery call for recent audits. There is no explicit guidance on when to prefer this over get_audit_status or get_audit_report, and no statement about prerequisites or when the list would be empty.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Report language, default en. | |
| name | No | Name shown in the report. | |
| model | No | openai-compatible only: the model name sent in the request body. | |
| levels | No | Subset of levels; default all 12 (plus 'agency' when tools are declared). | |
| headers | No | Headers the target needs, e.g. {"Authorization": "Bearer ..."}. A credential header is stored encrypted by BotArmor. | |
| min_grade | No | Pass threshold shown by get_audit_status, default B. | |
| target_type | No | Default: 'webhook' when endpoint_url is given, else 'prompt'. | |
| endpoint_url | No | Public https URL of the running agent (live audits only). localhost cannot be reached from BotArmor's servers. | |
| body_template | No | webhook only: JSON body with {{input}} (current message), "{{history}}" or "{{messages}}". Default {message: "{{input}}", session_id: "{{session_id}}"}. | |
| response_path | No | webhook only: dot path to the reply text in the response JSON, e.g. data.reply. | |
| system_prompt | Yes | The agent's system prompt / instructions, as in its code. For a live audit it is also the rulebook the judge checks answers against. | |
| authorization_confirmed | No | Live audits only. true = the user confirmed they own the bot or hold the owner's written permission to test it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare openWorldHint=true and destructiveHint=false; the description goes well beyond that by disclosing duration (5 to 20 minutes), cost (one audit credit), the asynchronous pattern (returns an id, poll with get_audit_status), the credential-encryption behavior for headers, and the authorization gate for live targets. The only missing behavioral detail is what happens on failure or whether credits are refunded on a failed audit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and mode split, and nearly every clause carries operational information. The parenthetical enumeration of attack personas ('fake manager, angry customer, fake lawyer...') is illustrative rather than actionable and makes the block longer than strictly needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter, nested-object tool with no output schema, the description covers what an agent needs: mode selection, authorization gate, what is returned (audit id), latency, cost, and the follow-up tools. Nothing required to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema only hints at: the 'agency' level applies to agents with tools, each level runs 5 adaptive sessions, and target_type selection is driven by whether endpoint_url is present. The system_prompt dual role (rulebook for the live judge) is also clarified beyond the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Crash-test a chatbot or AI agent with BotArmor') and immediately scopes what the crash-test consists of (up to 13 attack levels, 5 adaptive sessions each). It also makes clear this is the audit-launching tool, distinct from the read-only siblings get_audit_status, get_audit_report and list_audits, which it names as follow-up steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing rules for the two modes: 'prompt' when there is no endpoint_url, for localhost or undeployed agents; 'openai-compatible'/'webhook' for a live public https URL. It also states the hard prerequisite for live audits (authorization_confirmed: true, only after the user confirms ownership or written permission) and names the exact tools to call afterwards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1get_audit_reportget_audit_statuslist_auditsstart_auditScored 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.
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.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Free MCP security scan: tool-poisoning & prompt-injection audit (OWASP LLM01/08) + trust badge
