mspbots-agent-mcp

mspbots-agent-mcp

MCP server for the MSPbots Agent Platform API — exposes the Agent Platform'sconnector inventory, agent triggers (scheduled/event tasks), and per-agent policy(permissions, self-evaluation, human-in-the-loop approval) to MCP clients.

It follows the same design as the sibling ticketqa-mcp service: stateless, nostored credentials, per-request header authentication over theModel Context Protocol (Streamable HTTP/SSEtransport).

MSPbots Connector gives your AI clients one MCP URL to reach your entire MSP stack (RMM, PSA, documentation, security, finance), and gives you control over who can call which tool and a record of everything that was called.

Hosted service: connect.mspbots.ai · Free to use.

Why Connector

Quick start

1. Sign up at connect.mspbots.ai.
2. Connect your vendors. Pick from 150+ connectors and authorize each one on the vendor's own page, or bring your own API keys. No extra vendor accounts needed.
3. Set access. Create roles and decide which tools each role may call. Nothing is allowed until you allow it.
4. Add your MCP URL to your AI client. Copy the URL from your Connector dashboard into Claude, ChatGPT, Cursor, VS Code, Gemini, Codex, or any MCP-capable client.
5. Ask your AI to do real work, and watch every call appear in the audit log.

Features

Unified gateway

• One MCP URL for all your AI clients
• 150+ connectors across the MSP stack
• Custom MCP servers supported, free
• Authorization happens on each vendor's own page; the AI never sees passwords or tokens
• Bring your own credentials: use the vendor API keys you already have
• Multiple accounts per app; connect once, reuse across AI clients
• Tool search: finds the right action for the task
• One sign-in; vendor credentials are injected behind the scenes and OAuth tokens refresh automatically

Visibility

• Audit log for every tool call (who, which vendor, when)
• Usage dashboard: call volume, top vendors, error rate, per-user activity
• Export audit logs to CSV, or stream to Loki, Graylog, or LogScale (SIEM)
• Optional recording of tool arguments and result summaries (off by default, enabled per organization)

Control

• Per-role, per-tool allowlist, deny by default
• owner / admin / member roles
• SCIM provisioning with Entra ID, Okta, JumpCloud, and Google Workspace

Security

• Credentials encrypted one record at a time (AES-256-GCM, per-record key)
• AI clients authenticate with OAuth 2.1 + PKCE
• Vendor responses are scanned for prompt-injection patterns and returned as structured data. This is one layer of defense, not a guarantee against every attack.
• Static egress IP for customer firewall and API allowlisting

Pricing

Free.

Links: connect.mspbots.ai · mspbots.ai

When would you use this

This MCP is meta: it doesn't wrap a customer-facing integration, it wraps theAgent Platform's own admin/config API for an agent. The "users" are platformadmins/builders setting up an agent, or an agent introspecting/adjusting itsown configuration:

• "What connectors does this tenant have hooked up, and which are actuallyconnected right now?" → mspbotsagent_get_connectors
• "What connectors can this agent use / what does it pull data from?" →mspbotsagent_get_sop_data_sources (agent-scoped — notmspbotsagent_get_connectors, which is tenant-wide)
• "Make this agent run every Monday morning to summarize open tickets" →mspbotsagent_upsert_trigger (type recurring)
• "Kick this agent off automatically whenever a new ConnectWise ticket comesin" → mspbotsagent_upsert_trigger (type event, after checkingmspbotsagent_get_trigger_catalog)
• "Lock down what this agent is allowed to do without asking first" →mspbotsagent_upsert_agent_permissions
• "Require a human to sign off before this agent issues a refund" →mspbotsagent_upsert_agent_approval
• "Write up this agent's SOP so it has a documented, repeatable procedure" →mspbotsagent_set_sop_purpose / the other mspbotsagent_set_sop_* tools
• "What SOPs does this tenant have / which are still drafts?" →mspbotsagent_list_sops

Tools

Every tool takes its credentials from the request headers(X-API-Key / X-MSP-Tenant-Id / X-MSP-Host) — no token is ever passed as atool argument.

Connectors

mspbotsagent_get_connectors is tenant-scoped: it takes no agent_id andreturns the same inventory regardless of which agent is being configured. Forthe connectors a specific agent is declared to use, seemspbotsagent_get_sop_data_sources instead.

The two switch tools operate on individual tools within a connector. Aconnector's tools all default to on; the backend records only theexceptions (an opt-out list per agent + connector), so a tool with no overridereads enabled: true. capability_id is the connector id returned bymspbotsagent_get_connectors (or by a mspbotsagent_get_sop_data_sourcesentry). mspbotsagent_list_connector_tools returns the same tool names asmspbotsagent_get_sop_data_sources, adding each tool's enabled flag.mspbotsagent_set_connector_tools affects only the tool names you pass;enabled: false switches them off (the agent can no longer see or call them),enabled: true switches them back on. A change takes effect on the agent'snext chat — there is no ~30s restart to wait out and no need to start a newthread. For "all on / all off", read the current names first and pass the wholebatch in one call (restartRequired in the response is always true, butthe agent picks the change up on its next chat regardless; pending: truemeans the switch was saved but not yet synced to the agent's config).

mspbotsagent_get_connectors returns one row per connector:

Every connector the API returns also carries a very large base64 logo field —this service strips it to keep responses lean.

Backing endpoint: GET /apps/mb-platform-agent/api/capabilities/connectors, whichreturns {"success": true, "data": {"list": [ {connector}, ... ]}}.

Triggers (agent scheduled / event tasks)

A trigger runs an agent automatically: on a cron schedule (recurring) or when anevent fires in an external integration (event). Its primary key is taskId, and itbelongs to one agentId.

🚫 mspbotsagent_run_trigger is currently not exposed. Its @mcp.tooldecorator is commented out in src/mspbots_agent_mcp/tools/triggers.py, so itno longer appears in tools/list and cannot be called by external clients. Theimplementation stays in that file; re-enable by uncommenting the decorator(and the matching entry in tests/test_tools.py). The row above describes itas implemented; the other four trigger tools are unaffected.

Creating via upsert requires agent_id/name/prompt/type; recurring alsorequires schedule (cron, 1h minimum interval), and event requirestrigger_integration + trigger_events, whose combination must appear in theget_trigger_catalog catalog. When modifying, submit only the fields you want tochange.

Backing endpoints: GET|POST /api/tasks, PUT|DELETE /api/tasks/:taskId,GET /api/tasks/trigger-catalog, POST /api/tasks/:taskId/run.

Agent policy (permissions / evaluation / approval)

All three blocks of configuration hang off the same agent record: the reads shareone GET, and the writes share one partial PUT. So do not write to the same agentconcurrently (partial patches overwrite each other); and when a read comes back withpolicyError=true, the upsert tools refuse to write permission/interruptOn back(owners-only updates are unaffected) to avoid persisting a broken policy. The primarykey is agentId throughout.

Rule object shapes:

• evaluation rules[]: { rubric, name, description, triggers: [regex/keywords] }
• approval rules[]: { name, intent, triggers: [regex/keywords], tools: [...], decisions: [...] }

Backing endpoints: GET /api/agents/:id (shared by all three getters),PUT /api/agents/:id (shared by all three upserts, partial: writingpermission/interruptOn, review, and approval respectively).

Agent SOP author

An agent's SOP (standard operating procedure) draft has 5 independent fields, each withits own read and write tool, and each field writes through its own separate endpoint(unlike permission/evaluation/approval above, which share a singlePUT /api/agents/:id). Every write has the same shape: PUT {"value": ...}. Theprimary key is agentId.

Even though each field has a different endpoint, all 5 still live on the same agentrecord (the sopAuthor sub-document), so the rule frompermission/evaluation/approval applies here too: do not write to the same agent'sSOP fields concurrently, or they may overwrite each other. The SOP itself is adocument — a planning draft describing what the agent "should do"; thepermission/evaluation/approval config above is the behavior policy that actually takeseffect at runtime, deciding what the agent "can actually do". The two arecomplementary but distinct kinds of configuration.

🚫 The two *_sop_procedure tools are currently not exposed. Their@mcp.tool decorators are commented out insrc/mspbots_agent_mcp/tools/sop_author.py, so they no longer appear intools/list and cannot be called by external clients. The implementations stay inthat file; re-enable by uncommenting the two decorators (and the matching entries intests/test_tools.py). The rows below describe them as implemented; the other fourSOP fields are unaffected.

The dataSources value shape (each source stores only integration, nopreconditions):

{
  "sources": [
    { "integration": "open-meteo" },
    { "integration": "ms-graph" }
  ]
}

Every entry mspbotsagent_get_sop_data_sources reads back is a connector (an MCPserver available to the agent); besides integration it carries connection status anda tool list:

connection values:

Two easy mistakes, both written into the tool descriptions:

• connection is a single value and agent wins. When both levels are connected,connection shows only "agent", and the tenant half is only visible intenantConnected. There is currently no symmetric standalone agentConnectedboolean, so agent level can only be detected via connection === "agent".
• "none" and "unavailable" must be handled differently: the former really is notconnected (fine to prompt the user to go connect it), while the latter merely meansthe status could not be read (lean towards still-usable, and do not misreport it).

Summary test: usable = found === true and connection ∈ {agent, org} (withunavailable leaning usable); unusable = found === false or connection === "none".

mspbotsagent_get_sop_data_sources is the agent-scoped answer to"what connectors does this agent use", and its rows carry connectionstatus, so it usually answers "can this agent use X" on its own.mspbotsagent_get_connectors is the tenant-wide inventory— reach for it when the question is not about a particular agent.

Backing endpoints: GET|PUT /api/agents/:id/sop-author/{name,source,purpose,data-sources-list,procedure}.

Agent skills

🚫 Currently not exposed. These tools are commented out increate_mcp_server() (src/mspbots_agent_mcp/server.py), so they do not appear intools/list and cannot be called by external clients. The implementation stays insrc/mspbots_agent_mcp/tools/skills.py; re-enable by uncommenting the skillsimport and skills.register(...) call there (and the matching entries intests/test_tools.py). The rest of this section describes them as implemented.

The skills available to an agent come in three kinds: mspbots (built into theplatform), org (shared across the organization), and agent (private to that agent).Only private (agent) skills can be created/edited/deleted here; mspbots/orgskills can only be read, not changed. The primary key is capabilityId (the id oneach record from the list endpoint).

mspbotsagent_list_agent_skills returns, for each skill,id/type (mspbots|org|agent)/ref/scope/name/skillName/description/version/enabled/selected(true when not opted out)/available, plus a selectedIds list. selected isexactly the switch mspbotsagent_set_agent_skill_enabled writes, and each entry'sref and type are what to pass back in as ref and skill_type.

⚠️ The field structure of each element of files ("SkillFile") is not specified:the API spec handed over only said "$ref": "#/definitions/SkillFile", withoutattaching that definitions block.This implementation assumes {"path": "<relative path, e.g. 'SKILL.md'>", "content": "<raw text content>"}— inferred from the common SKILL.md packaging convention, not verified against thereal API. Confirm the actual field names with the backend before relying on it(whether there is also an encoding/executable, etc.).

Backing endpoints: GET /api/agents/:id/skills, POST /api/agents/:id/skills/create,PUT /api/agents/:id/skills/:capabilityId/files, PUT /api/agents/:id/skills,DELETE /api/agents/:id/skills(the last one's request body is {"id": "<capabilityId>"} — a DELETE with a body isunusual in HTTP, so this service sends it through httpx's low-level request()rather than delete()).

PUT /api/agents/:id/skills takes {ref, enabled, type} and answers{agentId, ref, enabled, restartRequired, pending}. restartRequired is alwaystrue. pending: true means the flag was recorded but syncing the install/uninstallto the runtime failed, so the agent's capability is marked pending and will be retriedlater — the change is not in effect yet. An unresolvable ref or an unknown agentcomes back as HTTP 200 with {"success": false, "error": "…"} rather than a 4xx, sothe tool checks success explicitly and reports it as an error.

SOP library (list + synchronous chat)

🚫 mspbotsagent_chat_with_sop is currently not exposed. Its @mcp.tooldecorator is commented out in src/mspbots_agent_mcp/tools/sops.py, so it nolonger appears in tools/list and cannot be called by external clients (itsdedicated tests in tests/test_sops.py are @pytest.mark.skip-ed to match).The implementation stays in that file; re-enable by uncommenting thedecorator (and the matching entry in tests/test_tools.py, and the skippedtests). Everything below describes it as implemented; mspbotsagent_list_sopsis unaffected and still exposed.

A SOP (standard operating procedure) is a tenant-level record, and creating onealso opens a dedicated agent for it. That agent is whatmspbotsagent_chat_with_sop talks to, which is why it takes only sop_id, neveragent_id. This is a different thing from Agent SOP author above:those tools edit the SOP draft sections attached to an agent, while these read theSOP library and actually run a turn of conversation.

mspbotsagent_list_sops returns the backend's GET /api/sops response as-is({total, list}; every field on each row, snake_case, nothing projected away —e.g. id/name/description/status/source/tags/agent_id/agent_live/updated_at).agent_live being false means that agent record no longer exists — the SOP is stillreadable, but it cannot be talked to, and no parameter on either tool can bring it back.

How "the user names a SOP in their own words" turns into a sop_id:the backend's search only does name ILIKE '%…%' (service/sop/db.ts:88) — it doesnot match description / tags / body, and there is no fuzzy, synonym or cross-languagematching. So a miss does not mean it does not exist; it usually just means thewording differs (the user says "the refund one", the SOP is called Refund Handling).Dropping the user's own words straight into search, getting 0 rows, and thenanswering "there is no such SOP" is the most expensive mistake on this path. The rightmove is to not pass search, read each row's name + description and pick ityourself, using total to decide whether to page. Use search only for a name fragmentyou already know for certain. This guidance lives in the search parameter's owndescription (parameter descriptions do not count towards the 500-char limit), and isguarded by test_search_param_warns_that_a_miss_is_not_an_absence intests/test_sops.py.

When you only have an agent_id: every list_sops row carries agent_id, so listthem and match on it to get the sop_id; mspbotsagent_get_usage_overview rows carryboth sopId and agentId too. Do not try to parse the agent's name — although a SOPagent is created as ${sop.name} #${sop.id} and renames propagate, PUT /api/agents/:idlets a user change name directly, which decouples it immediately, and an ordinaryagent can be given the same name too.

mspbotsagent_chat_with_sop returnssopId/sopName/agentId/threadId/status/reply, where status explains anempty reply:

reply is extracted the same way the frontend's lastAssistantText does it incomponents/assistant-ui/aegra/messages.ts: scan backwards for atype=ai/role=assistant message, skipping the internal messages the UI hides(rubric_grader, sop_context, sop_suffix, compact_summary, task_notification).

⚠️ This call path differs from the other tools in two ways — do not revert them tothe defaults:

1. It turns retries off (retries=0). A request that runs an agent is notidempotent — re-sending after a lost response runs the agent again instead ofrecovering the first result.
2. It raises the read timeout to 300s (the 30s default cannot survive a real agentturn; Aegra's own backstop is 1 hour). The error returned on timeout carriesretryable=false and says explicitly: do not re-send, ask again on the sameconversation instead.

Backing endpoints: GET /api/sops (returns {list, total} when paginated),GET /api/sops/:id (to get agent_id), POST /api/agents/:id/run/wait. That lastone signals a failed run with HTTP 200 + {"success": false} rather than a4xx/5xx, so this tool checks the success field explicitly to avoid reading a failureas "succeeded but said nothing".

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m mspbots_agent_mcp

Health Check

curl http://localhost:8080/health
# {"status": "ok"}

No credentials are required for the health endpoint.

Authentication

Every request to /mcp must include the following HTTP headers (provided by theMCP caller — kept consistent with ticketqa-mcp):

⏳ Transition (from 2026-09-23): X-API-Key replaces the formerX-MSP-Token. Credentials saved before the rename still sit in the registryunder the old name and the gateway injects them verbatim, so the middlewarefalls back to reading X-MSP-Token when X-API-Key is absent. When both arepresent X-API-Key wins. Once every tenant credential has been re-saved underthe new name, delete the fallback in server.py andtests/test_middleware.py::test_legacy_token_header_is_still_accepted.

X-MSP-Tenant-Id is not affected by this rename — still required, stillforwarded downstream.

Missing any of the three headers returns 401 Unauthorized.

Environment Variables

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP / SSE)
• Headers: X-API-Key, X-MSP-Tenant-Id, X-MSP-Host (all required)

Test Example

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: <token>" \
  -H "X-MSP-Tenant-Id: <tenant-id>" \
  -H "X-MSP-Host: https://agent.mspbots.ai" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "mspbotsagent_get_connectors", "arguments": {} }
  }'

⚠️ This is a public repository. Never write real tokens, tenant ids or othersensitive values into any committed file — the <token> / <tenant-id> above areplaceholders only.