eyas-mcp

eyas-mcp is an independent Model Context Protocol (MCP) server for the CrowdStrike Falcon platform. It connects AI agents to Falcon through FalconPy, with the aim of being a complete, agent-friendly integration layer for the Falcon APIs.

It's built for organizations to put under their own AI integrations: Claude, ChatGPT and the OpenAI Agents SDK, Gemini, GitHub Copilot, Cursor, or an assistant or agent of their own. Any MCP client can use it, and every tool declares whether it reads or changes tenant state so a client can decide what needs a person's approval.

Documentation

See the docs/ folder for configuration, usage and module reference. To connect a client, start with Client Integration. To build your own application or agent on eyas-mcp, see Building Your Own Integration.

Related MCP server: falcon-mcp

Modules

See the Module Overview for required API scopes, available tools, and FQL resources.

Quick Start

Install

eyas-mcp is installed directly from GitHub and isn't published to any package index:

uv tool install git+https://github.com/GTStagg/eyas-mcp.git

Configure

Set the required environment variables (or use a .env file — see the Configuration Guide):

export FALCON_CLIENT_ID="your-client-id"
export FALCON_CLIENT_SECRET="your-client-secret"
export FALCON_BASE_URL="https://api.crowdstrike.com"

Run

eyas-mcp

See the Getting Started guide for full installation and configuration details.

Client Integration

The example below is Claude Desktop's format, which most clients share. See Client Integration for Claude Code, VS Code with GitHub Copilot, Cursor, Gemini CLI, OpenAI Codex CLI, the OpenAI Agents SDK and the Responses API.

Using uvx (recommended)

{
  "mcpServers": {
    "eyas-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "--from",
        "git+https://github.com/GTStagg/eyas-mcp.git",
        "eyas-mcp"
      ]
    }
  }
}

With Module Selection

{
  "mcpServers": {
    "eyas-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "--from",
        "git+https://github.com/GTStagg/eyas-mcp.git",
        "eyas-mcp",
        "--modules",
        "detections,hosts,intel"
      ]
    }
  }
}

Docker

{
  "mcpServers": {
    "eyas-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/full/path/to/.env",
        "eyas-mcp:latest"
      ]
    }
  }
}

See the Usage guide for all command line options, module configuration, and library usage.

Container Usage

# Build the image from this repository
docker build -t eyas-mcp .

# Run with .env file (stdio transport)
docker run -i --rm --env-file /path/to/.env eyas-mcp:latest

# Run with streamable-http transport (add --api-key when the port is reachable beyond localhost)
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  eyas-mcp:latest \
  --transport streamable-http --host 0.0.0.0 --api-key your-secret-key

See the Docker Deployment guide for building from GitHub, pinning a commit, custom ports, and advanced configurations.

Dynamic Mode

Running many modules at once inflates the context window every AI client must hold. Dynamic mode replaces the full tool surface with three tools — falcon_list_enabled_tools to see every tool the server has available, falcon_search_tools to find candidate tools by keyword and then fetch the parameter schema for the one you pick, and falcon_execute_tool to run it — so agents only load the schemas they actually need.

eyas-mcp --dynamic
# or: FALCON_MCP_DYNAMIC=true

See the Dynamic Mode guide for the full discover → execute workflow and trade-offs.

Restricting What a Server Can Do

--modules is all-or-nothing per module: enabling one to get its search tools also exposes every mutating tool it carries. Three tool-level options narrow that surface.

# Investigation-only server: no tool that mutates tenant state is registered
eyas-mcp --read-only

# Expose exactly two tools, nothing else
eyas-mcp --tools falcon_search_detections,falcon_search_hosts

# Keep the module, drop one tool
eyas-mcp --modules hostgroups --exclude-tools falcon_delete_host_groups

# All of detections, plus one tool from a module you did not enable
eyas-mcp --modules detections --tools falcon_search_applications

Tool names are the falcon_-prefixed names your client displays. An unrecognized name aborts startup rather than being ignored, so a typo in a deny-list cannot silently leave a tool exposed.

Composing the options

--tools is additive, not a narrowing filter. It grants individual tools on top of whatever --modules already enabled, reaching across the module boundary:

• --tools X on its own registers only X — no modules are loaded by default.

• --modules detections --tools X registers every detections tool plus X, even when X belongs to a module that is not enabled. That module contributes only X, not its whole surface, and falcon_list_enabled_modules does not list it. falcon_list_enabled_tools does list X — it reports the tools available on the server, so it is the reliable answer to "is this capability available here?"

To subtract, use --exclude-tools or --read-only. All four knobs compose, and they resolve in a fixed order:

1. --exclude-tools removes a tool unconditionally, even if --tools names it.

2. --read-only removes every mutating tool unconditionally, even if --tools names it.

3. --tools adds the tools it names, bypassing the module gate.

4. --modules decides which tools are candidates by default.

Because the first two rules always win, --read-only and --exclude-tools are safe to set as a deployment-wide floor: an additive --tools list cannot widen past them. Combining them is how you express "search everything, change nothing, and don't even offer that one tool":

eyas-mcp --read-only --exclude-tools falcon_execute_rtr_read_only_command

Filtering applies to dynamic mode too — a withheld tool is absent from falcon_search_tools results and rejected by falcon_execute_tool. Because dynamic mode dispatches by name rather than registering tools individually, that rejection spells out that the tool exists but the server's configuration withholds it, and names the one rule responsible, so an agent reports a disabled tool as disabled instead of telling the user the capability does not exist. falcon_list_enabled_tools carries a filters_active field in either mode whenever a rule is in effect. The startup log reports which rules are active and how many tools --read-only and --exclude-tools withheld, so you can confirm what you deployed. Run with --debug to see the withheld tools by name.

These options filter tools, not resources. A withheld tool's FQL guide resource stays available — guides are static field documentation carrying no tenant data.

Deployment Options

• Docker

• Google Cloud (Agent Platform / Gemini Enterprise) (inherited example, not re-tested since the move to eyas-mcp)

Development

# Clone and install
git clone https://github.com/GTStagg/eyas-mcp.git
cd eyas-mcp
uv sync --all-extras

# Run tests
uv run pytest

Developer Documentation

• Documentation Guide: Architecture and maintenance guide for the documentation

• Module Development Guide: Instructions for implementing new modules

• Resource Development Guide: Instructions for implementing resources

• Integration Testing Guide: Guide for running integration tests with real API calls

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

This is a personal project with no support commitment. See SUPPORT.md.

Ideas, suggestions and feedback are welcome as GitHub Issues. Code contributions and outside pull requests aren't accepted; see CONTRIBUTING.