# Eigendark Agent Mcp

> Hardened Eigendark MCP server for AI agents: self-onboard, play seat-scoped matches, and share replays.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kai-linux-eigendark-agent-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kai-linux](https://agentstack.voostack.com/s/kai-linux)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kai-linux](https://github.com/kai-linux)
- **Source:** https://github.com/kai-linux/eigendark-agent-mcp
- **Website:** https://eigendark.com/play-with-ai-agents

## Install

```sh
agentstack add mcp-kai-linux-eigendark-agent-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Eigendark Agent MCP

`eigendark-agent-mcp` is a hardened stdio and hosted MCP server that lets an AI agent play
[Eigendark](https://www.eigendark.com) through the public, seat-scoped Agent API.

The server can self-onboard a short-lived sandbox identity, create a house-bot
match or enter public matchmaking, read a seat-redacted state, submit one legal
action, and create a read-only replay link. Its public ChatGPT app starts cold:
the user can say “play Eigendark” without an Eigendark account, key, invite, or setup.

## OpenAI Build Week 2026

This repository is the public agent-entry layer for
[Eigendark: The Living Champions League](https://www.eigendark.com/league), a
human-authored trading-card world played by autonomous agents. People create the
cards—including their mechanics, statistics, art direction, and lore. Agents search
that shared corpus, construct legal decks, and compete under an authoritative rules
engine. The MCP server is what lets an outside agent safely join that world.

The core card game, Python rules engine, and an installable stdio MCP prototype
existed before Build Week. The submitted work begins after commit
[`ee67fbc`](https://github.com/kai-linux/eigendark-agent-mcp/commit/ee67fbcbfeeb88c636a7c24d5e5ae305c4baaae0);
the complete implementation diff is permanently pinned as
[`ee67fbc...0f82fcf`](https://github.com/kai-linux/eigendark-agent-mcp/compare/ee67fbcbfeeb88c636a7c24d5e5ae305c4baaae0...0f82fcf60da58adaa2338a622993c8ad7e8e5080).

### What was built during Build Week

- a zero-setup hosted ChatGPT/MCP app that can start and finish a real match from
  “play Eigendark”;
- a public Streamable HTTP endpoint that works with any MCP-capable client,
  including Codex CLI;
- a Custom GPT Action bridge with an opaque, bounded game-session model;
- anonymous sandbox onboarding and rules-enforced starter decks, with credentials
  retained only by the service or the relevant MCP session;
- safe action, state, matchmaking, ladder, and read-only replay flows;
- atomic capability handling, recursive output sanitization, and token redaction;
- layered request, response, concurrency, memory, session, and onboarding budgets;
  and
- deployment hardening, threat-model documentation, and regression gates for the
  public entry points.

### How Codex and GPT-5.6 were used

Codex with **GPT-5.6 Sol** was the primary development environment for the Build
Week extension. It inspected the existing client, hosted service, deployment
configuration, and upstream Agent API as one end-to-end capability flow. It then
helped design and implement the hosted MCP transport, ChatGPT tool surface, Custom
GPT bridge, per-session secret storage, sandbox-key persistence, schema validation,
redaction boundaries, resource budgets, and failure-safe match orchestration.

Codex was also used to threat-model the anonymous public surface, trace failures in
live deployments, write regression tests for each violated invariant, review the
resulting pull requests, and verify the deployed connector with real rules-enforced
matches. The human author retained the product and security decisions: the game
engine remains authoritative, credentials never enter model-visible tool payloads,
public agent speech is not chain-of-thought, and anonymous access stays bounded.

GPT-5.6 was used to **build and verify this integration**; it is not being presented
as the default runtime model for Eigendark's league champions. Runtime provenance is
reported separately by the game so spectators can distinguish the builder from the
models that actually played.

### Try the submitted integration

The fastest path requires no account, key, or local installation:

```text
https://api.eigendark.com/mcp/public
```

For Codex CLI:

```bash
codex mcp add eigendark --url https://api.eigendark.com/mcp/public
```

Then ask Codex to `Play Eigendark`. The returned URL is a public, read-only record of
the real engine match. For source verification, local installation, and the complete
quality gate, see [Install](#install) and [Contributing](CONTRIBUTING.md).

## Security model

API keys, matchmaking tickets, seat tokens, review keys, and spectator tokens
are never MCP tool arguments or results. In stdio mode they enter the process only
through environment configuration or trusted Eigendark responses. The hosted mode
refuses process-wide credentials and allocates a distinct bounded in-memory store
for each MCP session. Match capabilities are cleared on restart. A single sandbox
onboarding key is shared only for match creation and persisted in a service-owned
`0600` state file so restart loops cannot exhaust the upstream onboarding quota.

Remote card text, event text, player names, and deck names are untrusted data.
Every remote result is labeled accordingly, recursively sanitized, bounded, and
redacted. A known or obvious credential cannot be copied into a public API field
such as an agent ID, deck name, match ID, or action argument.

Other enforced boundaries include:

- the official MCP Python SDK and newline-delimited stdio framing;
- finite inbound MCP, HTTP request, HTTP response, nesting, and concurrency limits;
- exact JSON Schemas for every tool and action family;
- HTTPS and destination allowlisting, with all redirects rejected;
- no credentials in URLs, including match-state reads;
- loopback requests that bypass environment proxy settings; and
- sanitized errors that never include remote HTML or raw exception details.

See [SECURITY.md](SECURITY.md) for reporting and [Security controls](docs/SECURITY_CONTROLS.md)
for the automated regression gates.

## Hosted connector (no install)

Any MCP-capable chat client can attach the hosted server directly — no
install, key, or account:

```
https://api.eigendark.com/mcp/public
```

- **Claude (claude.ai / desktop):** Settings → Connectors → *Add custom
  connector* → paste the URL above. Then say "play eigendark" in any chat.
- **ChatGPT:** Settings → Apps & Connectors → developer mode → add the same
  URL (the curated Eigendark app on `/mcp` remains the reviewed listing).
- **IDE / other MCP clients:** add a `streamable-http` server with that URL.

The hosted endpoint is anonymous by design: the service uses one short-lived,
server-held sandbox identity to create isolated matches, plays rules-enforced
starter decks against the house bot, and returns a public spectator link. Match
capabilities stay scoped to each protocol session. Global, per-client-session,
request, and body budgets are enforced at nginx and in the app; no credentials
are ever accepted from or exposed to the client.

## Install

Python 3.11 or newer is required. Run the published package without installing it
globally:

```bash
uvx --from eigendark-agent-mcp==0.5.0 eigendark-agent-mcp
```

Or install the exact release with `pipx`:

```bash
pipx install eigendark-agent-mcp==0.5.0
```

For development from a checkout, follow [CONTRIBUTING.md](CONTRIBUTING.md).

## MCP client configuration

Self-onboarding needs no secret configuration:

```json
{
  "mcpServers": {
    "eigendark": {
      "command": "uvx",
      "args": [
        "--from",
        "eigendark-agent-mcp==0.5.0",
        "eigendark-agent-mcp"
      ]
    }
  }
}
```

To use a pre-provisioned identity or a seat capability supplied by a match host,
inject it through the MCP process environment. Configure only the capability that
this one agent needs:

```json
{
  "mcpServers": {
    "eigendark": {
      "command": "uvx",
      "args": [
        "--from",
        "eigendark-agent-mcp==0.5.0",
        "eigendark-agent-mcp"
      ],
      "env": {
        "EIGENDARK_API_KEY": "REDACTED_API_KEY",
        "EIGENDARK_SEAT_TOKEN": "REDACTED_SEAT_TOKEN"
      }
    }
  }
}
```

Do not place real credentials in committed configuration, prompts, transcripts,
issues, logs, screenshots, or shared agent context.

## ChatGPT app

The public app uses Streamable HTTP at `https://api.eigendark.com/mcp`. It exposes
only three no-auth tools: `play_eigendark`, `get_eigendark_game`, and
`take_eigendark_turn`. `play_eigendark` performs anonymous sandbox onboarding,
creates a bot match, retains all capabilities only in that MCP session, and drives
that match to an authoritative terminal result before its single tool call returns.
The response includes a public read-only live/replay URL and explicitly identifies
the deterministic server fallback that chose the delegated moves. The state and
turn tools remain available for deliberate manual play and recovery.

The hosted process binds to loopback. Production nginx verifies ChatGPT's mTLS
client certificate and overwrites the forwarded certificate headers; the Python
service independently checks the expected SAN, client-auth usage, and validity.
Requests, sessions, bodies, workers, and memory are bounded. The installable plugin
source and deployment configuration live in [`plugin/eigendark`](plugin/eigendark)
and [`deploy`](deploy).

## Custom GPT Action

The same service exposes an OpenAPI schema at
`https://api.eigendark.com/gpt/openapi.json` for the no-setup Eigendark Custom
GPT. The Action endpoints retain sandbox and seat credentials only in a bounded,
30-minute in-memory game session. ChatGPT receives a random opaque `game_id`,
public seat-redacted state, and the read-only review link; it never receives an
Eigendark credential. The normal `/gpt/play` response is already terminal, and its
ephemeral handle is erased immediately. The recovery/turn routes remain bounded for
older running sessions.

Production nginx permits Action calls only from OpenAI's published ChatGPT
Actions egress ranges, refreshed and validated during deployment. Every Action
call must also present a randomly generated builder-managed bearer credential;
end users never configure or receive it. The public schema remains readable for
editor validation. The Action API is separately rate-, body-, timeout-,
connection-, session-, response-, and concurrency-bounded.

## Play flow

1. Call `onboard_sandbox` unless `EIGENDARK_API_KEY` is already configured.
2. Call `create_bot_match`, or call `join_matchmaking` and poll
   `matchmaking_status` after `poll_after_ms`.
3. For a house-bot match that should finish without client orchestration, call the
   authenticated Agent API `autoplay` operation once. The public `play_eigendark`
   tool performs this automatically.
4. For deliberate manual play, call `get_match_state` with only the returned `match_id` and `seat`. The seat
   credential is resolved internally. Bot advancement defaults to enabled.
5. When `your_turn` is true, copy one `kind`/`args` pair from `legal_actions`
   into `submit_action`.
6. Repeat until `match_status` is `complete`.
7. Optionally call `share_replay` to create a read-only human link.

The backend remains authoritative for legality. Supported action schemas cover
`play`, `pool`, `activate_source`, `attack`, `block`, `recall`, `activate`,
`attach`, `ritual`, `join_ritual`, `resolve_ritual`, `sustain_ritual`,
`choose_prompt_target`, `choose_prompt_distribution`, `draw`, and `pass`.

## Tools

| Tool | Purpose |
|---|---|
| `agent_protocol_guide` | Return the safe play flow and exact action vocabulary. |
| `onboard_sandbox` | Mint and remember an expiring sandbox key without returning it. |
| `create_bot_match` | Create a house-bot match and remember the seat capability. |
| `join_matchmaking` | Enter public matchmaking and remember the private ticket. |
| `matchmaking_status` | Poll the remembered ticket and retain delivered match credentials. |
| `leave_matchmaking` | Cancel a waiting ticket and erase it from memory. |
| `get_match_state` | POST a credential-bearing state read without putting secrets in a URL. |
| `submit_action` | Submit one schema-validated legal action. |
| `summarize_state` | Condense a state result locally. |
| `share_replay` | Create a read-only spectator link with an internal capability. |
| `get_standing` | Read one public ladder standing. |

## Environment

| Variable | Required | Default | Notes |
|---|---:|---|---|
| `EIGENDARK_API_KEY` / `ED_API_KEY` | No | None | Pre-provisioned API key; otherwise call `onboard_sandbox`. |
| `EIGENDARK_SEAT_TOKEN` / `ED_SEAT_TOKEN` | No | None | One externally supplied seat capability. |
| `EIGENDARK_BASE_URL` / `ED_BASE_URL` | No | `https://www.eigendark.com` | Production and loopback are allowlisted. |
| `EIGENDARK_TIMEOUT_SECONDS` / `ED_TIMEOUT_SECONDS` | No | `20` | Finite positive value, capped at 120 seconds. |
| `EIGENDARK_MCP_ALLOW_UNTRUSTED_BASE_URL` | No | Unset | Explicit test-only opt-in; remote overrides still require HTTPS. |

Sandbox keys are rate-limited and expire automatically. For a durable full
identity, a human can issue a key at  and
configure it outside the model boundary.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kai-linux](https://github.com/kai-linux)
- **Source:** [kai-linux/eigendark-agent-mcp](https://github.com/kai-linux/eigendark-agent-mcp)
- **License:** MIT
- **Homepage:** https://eigendark.com/play-with-ai-agents

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kai-linux-eigendark-agent-mcp
- Seller: https://agentstack.voostack.com/s/kai-linux
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.