MCP¶
Alkonos exposes an authenticated Streamable HTTP MCP server at:
https://api.alkonos.ai/mcp/console/
MCP lets an AI client search inventory, inspect findings, launch scans, and perform permitted mutations without constructing GraphQL requests manually.
Connect Claude Code¶
Open MCP & API Keys in Alkonos.
Create an organization-scoped API key.
Copy the generated command, or run:
claude mcp add alkonos \
--transport http \
https://api.alkonos.ai/mcp/console/ \
--header "Authorization: Bearer $ALKONOS_API_KEY"
For staging, use a staging API key and a separate server name:
claude mcp add ALKONOS_STAGING --transport http https://api-staging.alkonos.ai/mcp/console/ --header "Authorization: Bearer $ALKONOS_STAGING_API_KEY"
The console derives the MCP endpoint from the configured GraphQL API origin. Set VITE_MCP_URL at build time only when the MCP endpoint needs an explicit override.
Restart or reload the client if it does not discover the tools immediately.
The key dialog and onboarding AI tools step provide keyboard-accessible tabs for Claude Code, Codex, Cursor, VS Code, Gemini CLI, and Other. Select a client, then copy its command or configuration. Codex stores the key in ~/.codex/config.toml; keep that file private.
For another MCP client, configure a Streamable HTTP server at the same URL and send Authorization: Bearer <key> on every request. Configuration file shapes are client-specific.
Key permissions¶
The server exposes tools allowed by the key:
A read-only key can search assets, list groups, scans, scanners, and vulnerabilities, and inspect details.
An admin key can also create groups, add or remove group members, manage credentials, launch scans, comment on findings, assign findings, and change finding status.
Platform-admin tools appear only to superadmin keys. The
orgIdargument (act on another organization) also appears only to superadmin keys.
Use the least-privileged key that satisfies the workflow.
Response limits¶
List tools return at most 100 items per call (
firstorlimit). Use the cursor to get the next page.get_http_requestandget_ws_messagecut bodies to 4096 bytes by default, andget_vulnerabilitycutsrequestDataandresponseData. PassmaxBodyBytes: 0to get the full body;requestSize,responseSize, andpayloadSizealways give the full sizes.
Useful tool sequences¶
Asset IDs come in kinds: a host (dns_name) has ports, a repository has branches. Scans and findings attach to a port or branch. Filters named targetId take either one; a host or repository ID matches all its ports or branches.
Find a host and scan it¶
search_assets— find the host asset ID.get_host_ports— find the service port ID.list_scanners— optionally choose DAST agents.create_dast_scan— launch the scan.get_scan— poll status and per-agent progress.list_vulnerabilitieswithfilters.scanId— review results.
List the findings on a host¶
search_assets— find the host asset ID.list_vulnerabilitieswithfilters.targetIdset to the host ID.
For a whole group, use filters.assetGroupIdIn. The same filter on list_scans returns the group’s scans in one call; each row has memberId (the host or repository), so group the rows by it.
Show the traffic behind a finding¶
get_vulnerability— read the evidence,requestData/responseData, andscannerRunId.list_http_trafficwithsourceIds: [scannerRunId], plushostandpathfrom the evidence. For all traffic of the scan,get_scanand pass everyscannerRuns[].idand thecrawlIdinsourceIds. A scan ID matches nothing. To compare how much traffic each scanner run or the crawl sent, usecount_http_traffic_by_sourcewith the same filter: one call, one count per source.get_http_request— full headers and bodies for one request.
Create and populate a group¶
create_asset_groupadd_hostname_to_grouplist_asset_groupsorget_asset_groupsearch_assets
Triage findings¶
list_vulnerabilitiesget_vulnerabilityadd_vulnerability_commentassign_vulnerabilityupdate_vulnerability_workflow_status
Scan source code¶
Use get_repository_branches to find a branch asset ID, then list_scanners to choose an enabled scanner whose kind is SAST. Pass both branchId and scannerId to create_sast_scan; no scanner is selected by default. Repository branches are created after a connected repository is added and indexed.
For example, when list_scanners includes the enabled whitebox scanner:
{"branchId": "<branch-asset-id>", "scannerId": "whitebox"}
context is recorded as scan metadata, not detector guidance. The retired agi-sast scanner cannot be selected.
Example requests¶
List asset groups with critical or high findings. Do not change anything.
Find api.example.com, show its discovered ports, and ask me which port to scan.
Create a group named "Production API" with api.example.com as a seed, then show the created group ID.
List open critical findings, summarize the evidence and remediation, and leave their statuses unchanged.
For destructive or high-impact operations, include explicit group, asset, port, scan, or vulnerability IDs in the request and review the tool call before approval.