AuditHub MCP Server

This repository contains the source code of audithub-mcp, an MCP server for AuditHub.

audithub-mcp allows LLM-based agents to access functionality such as:

• Discovering information about AuditHub organizations and projects
• Launching and monitoring AuditHub tool tasks
• Accessing AuditHub issues and findings

By design, the MCP server limits the functionality to be read-only and non-destructive. Additional features can be enabled through the configuration file.

Warning: LLMs can make mistakes. Verify all tool outputs manually before acting on them.

Prerequisites

• Python 3.12+
• uv

Installation

audithub-mcp is implemented as a Python package, but it is not yet available in PyPI. You must install it directly from this repository.

Global Installation

If you are using the uv package manager, you can install audithub-mcp using uv:

uv tool install 'git+https://github.com/Veridise/audithub-mcp'
audithub-mcp --help

Local Clone

From the repo root:

uv venv
uv sync --active

If your virtual environment is already active and you just want to run the server entrypoint, use:

uv run audithub-mcp --help

Using audithub-mcp

To use audithub-mcp, you need to configure two parts: your agent and the audithub-mcp config file. Once both are configured, the agent should automatically start the MCP server and use its tools.

Agent Configuration

To enable audithub-mcp in your agent, you must add it to the MCP server config for your agent.

The following examples assume that audithub-mcp is available on PATH, and that your config file is located at ~/.config/audithub-mcp/config.yaml.

• Codex CLI
  • For interactive setup, use codex mcp add audithub-mcp
  • If you want to set it up with a config file, add the following to your .codex/config.toml:

    [mcp_servers.audithub-mcp]
    command = "audithub-mcp"
    args = ["--config", "~/.config/audithub-mcp/config.yaml"]

• Claude Code
  • For interactive setup, use claude mcp add audithub-mcp audithub-mcp
  • If you want to set it up with a config file, add the following to your .claude/mcp.json:

    {
      "mcpServers": {
        "audithub-mcp": {
          "command": "audithub-mcp",
          "args": [
            "--config",
            "~/.config/audithub-mcp/config.yaml"
          ]
        }
      }
    }

MCP Server Configuration

You will need to create a YAML file containing the audithub-mcp server creation and ensure that the agent configuration calls audithub-mcp with the --config <path> argument.

If you are not sure where to put the config file, a good default location is in ~/.config/audithub-mcp/config.yaml. The file permissions should be set to 400 (owner read-only) since it contains credentials.

See the config docs for details on how to create the configuration file.

Available MCP Tools

Tool	Description
get_organizations	List allowlisted organizations; pass details=true for full organization records and filter_id to narrow results
get_defi_vanguard_detectors	List all DeFi Vanguard detectors for an organization using the Vanguard listing block format
get_projects	List allowlisted projects in an organization; pass details=true for full project records and filter_id to narrow results
get_versions	List versions for a project; pass details=true for full version records, filter_id to narrow results, and latest_only=true for the latest version only
get_task_info	Get status and details for an AuditHub task
get_task_artifacts	List sanitized artifact metadata for an AuditHub task
get_task_artifact	Fetch a task artifact by ID as base64-encoded content
get_task_logs	Get logs for one or more steps of a task and write each result to a local output file
get_task_findings	Fetch findings for a task and write them to a local output file
wait_for_task_completion	Poll a task until no pending steps remain or the timeout is reached, then return the latest task snapshot and completion state; with no timeout, task-capable clients can invoke it as a task
parse_findings_from_task_log	Parse one or more task log files into JSON containing findings plus counts written to a local absolute output path
get_version_comments	Get comments for a specific project version
get_version_comment_threads	Get comment threads for a specific project version
get_thread_comments	Get comments for a specific thread within a project version
get_project_issues	Get all issues for a project
get_project_issue	Get a specific issue from a project
get_project_comments	Get all comments for a project across all versions
run_orca_task	Start an OrCa task for a project version; registered only when task runs are explicitly enabled
run_defi_vanguard_task	Start a DeFi Vanguard task for a project version; registered only when task runs are explicitly enabled
create_version_from_file	Create a project version by uploading a local .zip archive; registered only when version creation is explicitly enabled
create_version_from_url	Create a project version from a git repository or archive URL; registered only when version creation is explicitly enabled

All tools return typed Python objects backed by audithub-sdk models.

The objects returned by get_organizations, get_projects, and get_versions only exposes items belonging to organizations/projects on the configured allowlists.

Security Model

• Read-only by default. Default tools are named get_* and only invoke generated audithub-sdk GET endpoints.
• Task completion polling. wait_for_task_completion repeatedly fetches task details until no pending steps remain or the timeout is reached, then returns the latest sanitized Task snapshot with a boolean completion flag. When called with no timeout by a task-capable client, it can run as a task instead of blocking the request.
• Opt-in OrCa task execution. The run_orca_task mutation tool is registered only when AH_ENABLE_TASK_RUNS=1 or --enable-task-runs is supplied. It calls the generated OrCa POST endpoint through audithub-sdk.
• Opt-in DeFi Vanguard task execution. The run_defi_vanguard_task mutation tool is registered under the same task-run opt-in gate. Its inputs are flattened at the top level: organization_id, project_id, version_id, detector selections, and the runtime options. Pass detector selections as two-item JSON arrays [type, id], where builtin selectors use a built-in detector code from get_defi_vanguard_detectors, and custom selectors use the catalog id shown by the same tool. The server resolves those selections through the backend detector catalog before calling the generated DeFi Vanguard v2 POST endpoint.
• On-chain OrCa mode. When launching OrCa against already deployed contracts, pass deployment_info_file as a path ending in .deployment.json. The server normalizes that into on_chain=True and rejects mismatched paths early so callers do not accidentally launch a local Foundry-style run.
• Opt-in version creation. The create_version_from_url mutation tool is registered only when AH_ENABLE_VERSION_CREATION=1 or --enable-version-creation is supplied. It calls the generated project version URL POST endpoint through audithub-sdk.
• Local findings parsing. The parse_findings_from_task_log utility tool reads one or more local task log files, extracts findings with the shared log parser, and writes a JSON file containing the parsed findings plus the total finding count and per-log counts. It does not call the AuditHub API.
• Detector catalog cache. The DeFi Vanguard v2 built-in detector list is fetched lazily from the AuditHub configuration endpoint and cached in-process for one day. Custom detectors are fetched live on each request from both the organization library and the standard library.
• Detector listing format. get_defi_vanguard_detectors returns one block per detector. Each block starts with detector: <json> where <json> is a JSON value matching DefiVanguardV2DetectorSelectionInput, followed by title:. Standard-library custom detectors also include description: loaded from the detector payload. Each block ends with ------.
• Credential isolation. OIDC credentials are read from the environment once at startup and passed into audithub_sdk_ext.AuthenticatedApiClient. They are never accepted as tool arguments and are not surfaced in tool outputs or sanitized error messages.
• ID allowlisting. The server refuses to access any organization or project whose numeric ID was not explicitly included in AH_ALLOWED_ORG_IDS / AH_ALLOWED_PROJECT_IDS. The check runs before any network request.
• SDK-only transport. All AuditHub interaction flows through audithub-sdk and audithub_sdk_ext; there is no raw HTTP helper in the MCP server.

Development Workflow

• Run tests: uv run pytest
• Type check: uv run mypy
• Lint: uv run ruff check
• Format code: uv run ruff format

Override audithub-sdk Locally

To test audithub-mcp against a local checkout of audithub-sdk, add a path source override in the root pyproject.toml, then re-sync the environment.

Example root pyproject.toml override:

[tool.uv.sources]
audithub-sdk = { path = "/absolute/path/to/audithub-sdk", editable = true }

Then run:

uv sync --active

To return to the pinned version, remove the audithub-sdk entry from [tool.uv.sources] and run uv sync --active again.

License

Apache 2.0