Skip to content
AdminKit

Connect an AI agent to AdminKit's MCP server

AdminKit's MCP server connects an AI agent to AdminKit's live network-check tools: adminkit-mcp, a real, free, open-source connector published on PyPI and listed in the MCP Registry. Install it with uvx adminkit-mcp to expose 13 tools backed by AdminKit's Check API, each returning an explicit not-available status rather than fabricated data.

By AdminKit team, Netbase JSC · Updated

Key takeaways

  • adminkit-mcp is AdminKit’s free, MIT-licensed MCP server. You run it yourself with uvx adminkit-mcp, and any MCP client can then call its 13 tools.
  • The tools are thin clients over AdminKit’s live Check API at api.adminkit.net. Small volumes need no account; an API key unlocks the AI explainer and checks on verified assets.
  • Every tool returns the same envelope: status, result, evidence, fix_hint and report_url. A tool that can’t reach its backend says not_available instead of guessing.
  • For CI, adminkit-mcp probe <url> runs the MCP endpoint exposure check once and prints JSON, with no server process.

What does AdminKit’s MCP connector give you?

AdminKit’s MCP server overview lists the 13 tools. The connector behind them is real, tested, free code, published on PyPI — this guide covers installing and self-hosting it, and exactly which tools return real results. It’s one piece of AdminKit’s AI agents & MCP cluster, which covers connecting, securing, and checking the exposure of MCP servers and the agents that call them.

Before you start, check these four things:

You needWhy
An MCP-capable client (Claude Desktop, Claude Code, an IDE, or your own agent)It starts the server and passes tool calls to it
uv, or Python with pipuvx downloads and runs the package in an isolated environment
Outbound HTTPS to api.adminkit.netEvery tool except the local endpoint probe calls the Check API
Optional: an AdminKit API keyOnly for explain_report’s AI step and checks on verified assets

How do you install adminkit-mcp?

It’s published on PyPI: pypi.org/project/adminkit-mcp (adminkit-mcp 0.1.0, MIT licensed) and listed in the MCP Registry as io.github.netbasecorp/adminkit-mcp. Install it with uvx:

uvx adminkit-mcp

# or streamable HTTP, for a remote/network client
uvx adminkit-mcp --http :8080

The default (no --http flag) serves over stdio, the usual transport for a locally-spawned MCP client like Claude Desktop or an IDE integration. Point your MCP client’s server config at the uvx ... command above (stdio) or http://localhost:8080 (Streamable HTTP), the same as any other local MCP server. If you serve over HTTP on anything other than your own machine, put authentication in front of it: an MCP server that answers anyone is exactly what AdminKit’s MCP endpoint check flags.

Prefer pip? pip install adminkit-mcp works the same way. Source is public at github.com/netbasecorp/adminkit-mcp (tag v0.1.0) if you’d rather install from the git tag directly: uvx --from git+https://github.com/netbasecorp/adminkit-mcp@v0.1.0 adminkit-mcp. The server is built on the official MCP Python SDK.

How do you add it to your MCP client?

Clients that start local servers from a JSON file use the mcpServers structure described in the MCP project’s guide to connecting local servers. For Claude Desktop the file is claude_desktop_config.json (under ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows). An entry for adminkit-mcp, with one optional setting passed through env, looks like this:

{
  "mcpServers": {
    "adminkit": {
      "command": "uvx",
      "args": ["adminkit-mcp"],
      "env": { "ADMINKIT_MCP_TIMEOUT_SECONDS": "15" }
    }
  }
}

Restart the client after saving the file. In Claude Code, the claude mcp add command does the same from a terminal; everything after -- is the command that starts the server, and --env passes environment variables:

claude mcp add --transport stdio adminkit -- uvx adminkit-mcp

Which environment variables does it read?

VariableDefaultPurpose
ADMINKIT_API_BASEhttps://api.adminkit.netCheck API base URL — live in production.
ADMINKIT_SITE_BASEhttps://adminkit.netResilience fallback base for the three tools that have one.
ADMINKIT_API_KEYunsetOptional API key, attached as X-API-Key; never logged.
ADMINKIT_MCP_TIMEOUT_SECONDS10.0HTTP timeout for both backends.
ADMINKIT_MCP_RATE_LIMIT_PER_SECOND5.0Client-side rate limit applied to outbound calls.
ADMINKIT_MCP_ALLOW_PRIVATEfalseAllow check_mcp_endpoint to probe loopback/private targets (CI use only).

A client-side timeout like ADMINKIT_MCP_TIMEOUT_SECONDS is a blunt instrument: it just stops waiting. MCP’s own cancellation notification is a cleaner alternative where a client supports sending it, since it tells the server to actually stop the in-progress request instead of leaving it running unseen after the caller has already given up.

Keep the API key out of files you commit. Set it in your shell or your client’s secret store, and pass it through as an environment variable rather than writing it into a shared configuration file.

Which of the 13 tools actually return real data?

Every tool first tries the real AdminKit API (/v1/check/..., or /v1/tools/... for the utilities), and that API is live in production at api.adminkit.net (see the OpenAPI reference). A route only falls back or reports “not available” if that specific call is briefly unreachable — it’s a resilience path, not the normal case. What happens differs by tool:

ToolBehaviour once self-hosted
check_mcp_endpointWorks fully. Tries the live Check API first, falls back to a local, self-contained probe if that call is unreachable.
check_ipWorks. Reports on the public IP making the request; calls the live Check API and falls back to AdminKit’s live site function (adminkit.net/api/ip) if that route is ever unreachable.
dns_lookupWorks. Calls the live Check API; falls back to the live site’s DNS function (adminkit.net/api/dns) if that route is ever unreachable.
check_mail_authWorks. Calls the live Check API; falls back to the live site’s SPF/DMARC function (adminkit.net/api/mailauth) if that route is ever unreachable.
check_domainWorks. Calls the live Check API’s whois/TLS/HTTP-header checks in parallel; no site fallback, so an individual sub-check that’s briefly unreachable is dropped from the aggregate rather than fabricated.
check_owned_portsWorks. Calls the live Check API’s ownership-gated port check (find open ports you own from your AI assistant); reports “not available” instead of a fabricated result if that route is briefly unreachable.
explain_reportWorks, with your own API key. Fetches a saved report from the live Check API, then asks the live AI explainer — that second call needs your own ADMINKIT_API_KEY; without one (or if AI isn’t enabled on the deployment it talks to) it reports “not available” rather than guessing.
get_radarWorks. Reads live, aggregated honeypot/telemetry trend data from the Check API (k ≥ 5 only) for one protocol: mqtt, modbus, mcp, rtsp, telnet or dns.
subnet_calc, ip_info, ipv6_info, mac_vendor, user_agentWork. Pure calculation over the input you pass, done by AdminKit’s API (/v1/tools/...); no third-party host is contacted, invalid input comes back as a plain error, and an unreachable API is reported as “not available”.

None of the “not available” responses fabricate a result — each returns the same envelope shape (result, evidence, fix_hint, report_url) with a plain message saying what isn’t reachable right now and a link to the matching public page, so an agent calling the tool gets a clear, structured answer either way.

What does every tool return?

All 13 tools share one response envelope, so an agent can handle them the same way and cite what it found:

FieldContent
toolThe tool’s name, for example dns_lookup
statusok, warn, fail, error, skipped or not_available
resultThe structured answer: summary, findings, score where the check computes one
evidenceThe raw data behind the answer, such as DNS records or HTTP status codes
fix_hintOne plain next step, or null when there is nothing to fix
report_urlA link to the matching public AdminKit page, tagged utm_source=mcp

How do you confirm the connection works?

Start with tools that need no input you have to look up. Ask your agent: “Use check_ip to show my public IP and network”, then “Use subnet_calc on 192.0.2.0/24”. The first proves the connector can reach the Check API; the second exercises a utility with a documentation range whose answer you can check by hand (256 addresses, 254 usable hosts).

SymptomLikely causeFix
The client doesn’t list any AdminKit toolsConfig not loaded, or uvx not on the client’s PATHRestart the client; use the full path to uvx in command
Every tool returns not_availableNo outbound HTTPS to api.adminkit.netCheck proxy or firewall rules on the machine running the connector
explain_report returns not_availableNo ADMINKIT_API_KEY setAdd the key through the client’s env setting
check_owned_ports returns skippedThe IP is not yours or not verifiedSee the ownership rules in the ports guide

Claude Desktop writes MCP logs to ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows, according to the MCP project’s guide; a file named after your server holds its standard error output.

How do you run a one-shot probe without a server?

If you only need the endpoint-exposure check — the same one the GitHub Action runs in CI — you don’t need to run a server at all:

uvx adminkit-mcp probe https://mcp.example.com/mcp

This prints the probe’s JSON result (url, status, summary, score, findings, evidence), runs entirely on your machine, and is exactly what the GitHub Action calls under the hood. It exits with a non-zero code only when the target cannot be reached.

Why does this matter for agent builders?

If you’re building an agent that needs to check its own exposure, or a user’s, before acting — whether an MCP endpoint is safe to call, whether a domain’s mail setup looks wrong, what a caller’s own IP looks like — self-hosting lets you start integrating right away: all 13 tools call a real backend, and the ones that can’t finish a specific call return an explicit not-available status instead of silently returning nothing or guessing. See our AI agent builders solutions page and the MCP endpoint check tool page for the fuller picture, and our guide to securing an MCP server if you’re the one building the server an agent like this would call. The Model Context Protocol specification also says clients should keep a human able to deny tool calls, so expect your client to ask before each call until you allow a tool.

Where does AdminKit fit on the server side?

The MCP & Agent Gateway is a different, complementary piece that Netbase deploys and runs for you as a custom engagement: it sits in front of your MCP server to enforce auth and tool allowlists, rather than being a set of tools an agent calls outward. Self-hosting adminkit-mcp gives an agent the outward-facing check tools; the gateway protects the inward-facing server side — talk to our team if you want it in front of your server.

This guide is general information, not a security audit of your specific network — see our disclaimer for what AdminKit's guidance does and does not commit to.

Frequently asked questions

Is adminkit-mcp published on PyPI?

Yes. `adminkit-mcp` 0.1.0 is published on PyPI (pypi.org/project/adminkit-mcp) and listed in the MCP Registry as `io.github.netbasecorp/adminkit-mcp`. Install it with `uvx adminkit-mcp` or `pip install adminkit-mcp`. The source is also public on GitHub (github.com/netbasecorp/adminkit-mcp, MIT) if you'd rather install from a git tag.

Which of the 13 tools actually return real data when I self-host it?

All of them call a real backend. check_mcp_endpoint always works, because it can fall back to a local probe. check_ip, dns_lookup and check_mail_auth call AdminKit's live Check API with a fallback to AdminKit's live site functions if that route is ever unreachable. check_domain, check_owned_ports and get_radar call the live Check API directly. explain_report also calls the live Check API but needs your own ADMINKIT_API_KEY for its AI step. The five utilities (subnet_calc, ip_info, ipv6_info, mac_vendor, user_agent) send your input to AdminKit's API for pure calculation, contact no third-party host, and report not_available if the API can't be reached.

Does this call the live, hosted mcp.adminkit.net/mcp endpoint?

No — that hosted endpoint is a separate, different thing (see /developers/mcp/). This guide is about running the open-source connector yourself, which talks to AdminKit's Check API (api.adminkit.net) directly, not to a hosted MCP endpoint.

Can I run it over HTTP instead of stdio, for a remote agent?

Yes — adminkit-mcp --http :8080 serves streamable HTTP on that host:port instead of stdio. The default (no --http flag) serves over stdio, the usual transport for a locally-spawned MCP client like Claude Desktop or an IDE integration.

Is there a one-shot command for CI, without running a full server?

Yes — adminkit-mcp probe <url> runs the endpoint-exposure probe once and prints JSON, no server process involved. This is also what the AdminKit GitHub Action uses under the hood.

Do I need an AdminKit API key?

Not for most tools. The Check API answers small volumes anonymously, with a per-IP rate limit. A key, set in the ADMINKIT_API_KEY environment variable, is needed for explain_report's AI step and for checking ports on an IP your organisation has verified. The connector sends it as an X-API-Key header to AdminKit's API only, never to a server you are probing, and never logs it.

Want AdminKit to watch this for you?

Free checks tell you the state today. Protective DNS and monitoring tell you when it changes.

Huy Nguyen (David), Founder and CEO of Netbase JSC

Talk to an expert

Huy Nguyen (David), Founder & CEO, Netbase JSC

Ask whether this fix applies to your setup, or get a second pair of eyes on your DNS and mail records.