# ISO-toolset MCP

A vendor-neutral MCP gateway for starting, discovering, calling, and stopping
security-vendor MCP runtimes without requiring every analyst to install each
vendor integration or handle its credentials.

> **Status: v0.1 reference implementation.** The local MCP gateway is runnable.
> The AWS template establishes the scale-to-zero control-plane skeleton. Okta,
> production authorization and the Fargate request/result worker are explicit
> integration boundaries, not completed features. The unmodified Cortex MCP
> package is included under Palo Alto Networks' separate vendor license.

## What an analyst sees

Claude Code connects to one MCP server and sees five stable tools:

```text
cortex-start
cortex-status
cortex-help
cortex-call
cortex-stop
```

The downstream call path is:

```text
Claude Code
  -> ISO-toolset MCP gateway
  -> private Cortex MCP runtime
  -> Cortex HTTPS API
  -> sanitized MCP result back to Claude Code
```

`cortex-call` is an ISO-toolset broker tool, not an official Cortex tool. It
takes a live downstream tool name and arguments, validates them against the
schema discovered from Cortex, forwards the MCP call, and preserves useful
errors without leaking sensitive runtime details.

## Local development

Requirements: Python 3.11+ and a Cortex MCP server running with Streamable HTTP.
The vendor ZIP is available at `vendor/cortex/cortex-mcp-1.0.5.zip`; review its
separate license and README before building or running it.

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
export CORTEX_MCP_URL='http://127.0.0.1:8080/api/v1/stream/mcp'
iso-toolset
```

The default transport is stdio, suitable for a local MCP host. To expose the
development Streamable HTTP endpoint:

```bash
export ISO_TOOLSET_TRANSPORT=streamable-http
iso-toolset
```

The endpoint is:

```text
http://127.0.0.1:8000/ISO-toolset/v1/mcp
```

This local mode attaches to an existing Cortex process. Therefore
`cortex-stop` closes the logical ISO-toolset session but does not terminate a
process it does not own.

## Error behavior

Known argument errors are returned before the downstream call:

```json
{
  "ok": false,
  "error": {
    "code": "INVALID_TOOL_ARGUMENTS",
    "message": "Invalid arguments for 'get_assets' at $: 'asset_type' is required",
    "retryable": true,
    "details": {"path": "$", "validator": "required"}
  }
}
```

Claude can correct the parameters and retry. Downstream errors are sanitized,
tagged, and returned rather than collapsed into a generic failure.

## AWS scale-to-zero direction

[`infra/template.yaml`](infra/template.yaml) declares:

- a custom EventBridge bus and runtime-command rule;
- encrypted SQS control and dead-letter queues;
- a DynamoDB session table with TTL;
- an ECS cluster and ephemeral Fargate task definition;
- an outbound-only runtime security group;
- a control Lambda that calls `RunTask` and `StopTask`;
- least-scope starting IAM roles and CloudWatch logs.

CloudFormation creates the reusable infrastructure. A normal `cortex-start`
does **not** run CloudFormation; it publishes a runtime command that ultimately
calls ECS `RunTask`. A normal `cortex-stop` calls ECS `StopTask`.

Read [the architecture](docs/ARCHITECTURE.md) and
[the threat model](docs/THREAT_MODEL.md) before deploying anything.

## Deliberately not included

- A prebuilt Cortex container image. Build the included, checksum-pinned vendor
  archive only after reviewing its license, then store the resulting image in a
  private ECR repository.
- API keys, example secrets, tenant URLs, or organization identifiers.
- A claim that the reference AWS template is production-ready.
- GPU sweeps, EC2 shutdown automation, notifications, or write-capable tools.

## Tests

```bash
python -m pip install -e '.[dev]'
ruff check .
pytest -q
```

## License

The ISO-toolset source is MIT licensed. The Cortex MCP ZIP is not: it remains
under the Palo Alto Networks license included inside the archive and at
`vendor/cortex/LICENSE`. See [third-party notices](THIRD_PARTY_NOTICES.md).