BeVigil MCP Server

An MCP (Model Context Protocol) server that provides AI-native access to the BeVigil OSINT API for mobile application security research and asset discovery.

✅ Tested with Claude Code, Codex and VS Code.

What is this?

This project bridges BeVigil's mobile application intelligence platform with MCP-compatible AI clients (such as Claude Code, Codex and VS code). It allows AI agents to perform security research tasks such as discovering hosts, subdomains, S3 buckets, and API endpoints extracted from mobile applications — all through well-designed, validated MCP tools.

Why does it exist?

Security researchers and developers often need to investigate the infrastructure behind mobile applications. BeVigil indexes millions of Android apps and extracts security-relevant assets. This MCP server makes that intelligence directly accessible to AI agents, enabling automated OSINT workflows without manual API interaction.

Architecture

MCP Client (Claude, etc.)  →  BeVigil MCP Server  →  BeVigil OSINT API
         ↕                           ↕                       ↕
    AI prompts              Tool validation &          osint.bevigil.com
    & responses             response formatting

Features

Available Tools

Tool	Description
bevigil_get_hosts	Get hostnames/domains found in an Android app's code
bevigil_get_subdomains	Discover subdomains associated with a domain
bevigil_get_urls	Get URLs associated with a domain
bevigil_get_s3_buckets	Find S3 buckets referenced in an Android app
bevigil_get_app_packages	Find Android apps that reference a given hostname
bevigil_get_wordlist	Get wordlist (paths, endpoints, params) from an app
bevigil_investigate_app	Multi-step investigation — combines hosts, S3, params, and wordlist into a structured report

Key Design Decisions

• 7 focused tools instead of raw API wrappers — designed for what AI agents actually need
• Result truncation with counts and warnings to preserve LLM context windows
• Concurrent lookups in the investigation workflow for efficiency
• Partial failure handling — returns available data even when some lookups fail
• Security disclaimers — findings are labeled as observed data, not confirmed vulnerabilities

Requirements

• Node.js 18 or higher
• BeVigil API key — get one free at bevigil.com
• An MCP-compatible client (Claude Code, Codex, VS Code, etc.)

Installation

# Clone the repository
git clone <repository-url>
cd bevigil-mcp-server

# Install dependencies
npm install

# Build
npm run build

Configuration

API Key

Set your BeVigil API key as an environment variable:

export BEVIGIL_API_KEY=your_api_key_here

Or create a .env file (see .env.example):

BEVIGIL_API_KEY=your_api_key_here

MCP Client Configuration

Claude Code

Add the server with the CLI:

claude mcp add bevigil -e BEVIGIL_API_KEY=your_api_key_here -- node /absolute/path/to/bevigil-mcp-server/build/index.js

Or add it manually to your .mcp.json (project scope) or ~/.claude.json (user scope):

{
  "mcpServers": {
    "bevigil": {
      "command": "node",
      "args": ["/absolute/path/to/bevigil-mcp-server/build/index.js"],
      "env": {
        "BEVIGIL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Verify it's registered with claude mcp list.

Codex

Add the server with the CLI:

codex mcp add bevigil --env BEVIGIL_API_KEY=your_api_key_here -- node /absolute/path/to/bevigil-mcp-server/build/index.js

Or add it to ~/.codex/config.toml (user scope) or .codex/config.toml (project scope):

[mcp_servers.bevigil]
command = "node"
args = ["/absolute/path/to/bevigil-mcp-server/build/index.js"]

[mcp_servers.bevigil.env]
BEVIGIL_API_KEY = "your_api_key_here"

Verify it is registered with codex mcp list.

VS Code (Copilot)

Add to your VS Code MCP settings:

{
  "mcp": {
    "servers": {
      "bevigil": {
        "command": "node",
        "args": ["/absolute/path/to/bevigil-mcp-server/build/index.js"],
        "env": {
          "BEVIGIL_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Usage Examples

Once configured, you can ask your AI assistant things like:

Investigate the WhatsApp Android app (com.whatsapp) using BeVigil and summarize what infrastructure it exposes.

Find all subdomains associated with example.com that appear in mobile applications.

What S3 buckets are referenced in the com.instagram.android app?

Which Android apps communicate with api.example.com?

Show me the API endpoints and paths extracted from com.example.app.

Running Tests

npm test

Tests use Node's built-in test runner with mocked API responses — no live API calls are made during testing.

Project Structure

├── src/
│   ├── index.ts              # MCP server entry point
│   ├── bevigil-client.ts     # BeVigil API client (auth, errors, timeouts)
│   ├── types.ts              # Shared types and output helpers
│   └── tools/
│       ├── hosts.ts          # bevigil_get_hosts
│       ├── subdomains.ts     # bevigil_get_subdomains
│       ├── urls.ts           # bevigil_get_urls
│       ├── s3-buckets.ts     # bevigil_get_s3_buckets
│       ├── packages.ts       # bevigil_get_app_packages
│       ├── wordlist.ts       # bevigil_get_wordlist
│       └── investigate.ts    # bevigil_investigate_app
├── tests/
│   ├── bevigil-client.test.ts  # API client tests
│   ├── tools.test.ts           # Tool helper tests
│   └── fixtures/
│       └── responses.ts        # Mock API response fixtures
├── package.json
├── tsconfig.json
└── .env.example

Limitations

• Mobile app data only — BeVigil's intelligence comes from analyzing Android applications. Results reflect what's embedded in app code, not comprehensive DNS or internet-wide scanning.
• Free tier credits — Free accounts get 25 API credits (200 with a work email). Each API call consumes credits. The investigation tool makes 4 API calls per invocation.
• No app search — The BeVigil API requires you to know a package ID or domain. There is no search/listing endpoint to discover apps by name.
• No app metadata — The API does not return app names, descriptions, or store information — only security-relevant assets.
• Data freshness — Results reflect BeVigil's most recent analysis of each application, which may not be real-time.
• Rate limits — The API uses a credit-based system. If you exhaust your credits, requests will fail with a clear error message.

Security

• API keys are loaded from environment variables only — never hardcoded or logged
• Error messages never expose credentials
• The server only communicates with known BeVigil API endpoints — no arbitrary URL fetching
• All tool inputs are validated with Zod schemas
• Request timeouts prevent hanging connections
• Result sizes are capped to prevent context overflow

License

MIT