mcp

# @gripforgeai/mcp

**The tools your AI needs to make your games.**

Turn prompts into production-ready game assets — animated characters with their weapons attached, seamless textures, terrain, VFX, HUDs — and playable game kits.

MCP client for the [GripForge](https://gripforge.ai) API — from Claude Code, Cursor, Windsurf, VS Code or any MCP client.

## How to use

**Hosted — nothing to install.** Point any remote-capable MCP client at `https://gripforge.ai/mcp`
with your API key ([create one here](https://gripforge.ai/account)):

```jsonc
{
  "mcpServers": {
    "gripforge": {
      "url": "https://gripforge.ai/mcp",
      "headers": { "x-api-key": "gf_..." }
    }
  }
}
```

**Claude Code**, in one line:

```bash
claude mcp add --transport http gripforge https://gripforge.ai/mcp --header "x-api-key: gf_..."
```

**Local, via npm** — when the agent must write files into your repository:

```jsonc
{
  "mcpServers": {
    "gripforge": {
      "command": "npx",
      "args": ["-y", "@gripforgeai/mcp"],
      "env": { "GRIPFORGE_API_KEY": "gf_..." }
    }
  }
}
```

## Key features

- **Characters that move.** Describe one, get a rigged T-pose with an animation set — idle, run,
  attack — ready to drop into a scene.
- **Weapons in hand.** GripForge finds the hand bone on any rig, scales the prop, closes the fist
  around the grip, and returns the bind plus Three.js, Unity and Godot snippets.
- **Seamless textures.** Tileable material sets from a prompt or from your own image, upscaled
  without invention.
- **Terrain and maps.** Playable room graphs, top-down shooter layouts with spawns and lanes,
  greybox reconstruction from references.
- **VFX and HUD.** Animated effects and interface kits exported for your engine.
- **Playable game kits.** Assemble modular capabilities — movement, combat, enemies, worlds — into
  a game that runs in the browser, then bind your own assets to it.
- **One Library.** Everything generated lands in a locker your engine can pull from, and that your
  agent can search by look ("Devil May Cry like", "genshin").

## Use cases

- *"Attach this sword to my knight, right hand, then export the armed GLB."* — the agent handles the
  bone, the scale and the fist; you get a file that loads.
- *"Make me a boss for an ashen underworld, with three phases and an arena."* — stats, attacks and
  engine snippets come back together.
- *"Give this floor a mossy cobblestone texture that tiles."* — a seamless set, saved to the Library.
- *"Build a playable roguelike slice I can try in the browser."* — a game kit project with its
  assets bound, playable from a link.

## FAQ

**Do I need to install anything?** No. The hosted endpoint works from any MCP client that speaks
streamable HTTP. The npm package exists for one reason: letting the agent write files directly into
your repository.

**Which engines are supported?** Unity, Godot, Unreal and Three.js — assets come with the binds and
snippets each one expects.

**How is it billed?** Credits, per generation. Reading the Library, animating an existing character,
level and map kits cost nothing; generating a character or a weapon costs 10.

**Where do my assets live?** In your workspace Library. You can pull them into your repository, push
your own, and share them with the community catalog.

**Can I use my own concept art?** Yes — pass an image and GripForge builds the T-pose sheet from it
rather than inventing a character.

## Hosted endpoint

No Node required — point any remote-capable MCP client at:

```
https://gripforge.ai/mcp
```

Auth: `x-api-key: gf_...` header (or `Authorization: Bearer`). Assets are passed
as **URLs** (`character_url`, `prop_url`) — Tripo/Meshy download links work
directly.

```jsonc
// Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "gripforge": {
      "url": "https://gripforge.ai/mcp",
      "headers": { "x-api-key": "gf_..." }
    }
  }
}
```

## Example

> "Attach this sword to my knight, right hand, then export the armed GLB."

The agent calls `gripforge_attach` with the two asset URLs (or local paths with
the npm package); GripForge finds the hand bone, scales the prop to the
character's hand, closes the fist around the grip and returns the bind JSON,
ready-to-paste Three.js / Unity / Godot snippets, and optionally the armed GLB.

To forge a character **from a picture** (not from a text prompt), pass
`concept_item` (a Library `lib_…` T-pose/concept), or with the npm package a
local `path` / `file_url`. That is Meshy image-to-3D. Without those fields the
tool is text-to-3D only.

## Install (any MCP client)

Add the server to your client's MCP config (`.mcp.json`, `mcp.json`, settings — the shape is the same everywhere):

```json
{
  "mcpServers": {
    "gripforge": {
      "command": "npx",
      "args": ["-y", "@gripforgeai/mcp"],
      "env": { "GRIPFORGE_API_KEY": "gf_..." }
    }
  }
}
```

Get an API key at https://gripforge.ai/login — Free: 15 Studio attaches + **3 API/MCP trial attaches / month**. Credit packs from €29 (100 credits, never expire).

## Install (Grok)

```bash
grok mcp add gripforge --env GRIPFORGE_API_KEY=gf_... -- npx -y @gripforgeai/mcp
```

Or in `~/.grok/config.toml`:

```toml
[mcp_servers.gripforge]
command = "npx"
args = ["-y", "@gripforgeai/mcp"]
enabled = true
startup_timeout_sec = 45

[mcp_servers.gripforge.env]
GRIPFORGE_API_KEY = "gf_..."
```

Also works with Cursor, Windsurf and any MCP-compatible client — same
`command` / `args` / `env` triple.


## Tool reference

Hosted HTTP MCP (`https://gripforge.ai/mcp`) is always current. This npm package
writes files into the repo (`out_dir`), including `gripforge_hud`,
`gripforge_hud_bar` and `gripforge_cape`. Hosted-only: `gripforge_make_seamless`.
Full list: https://gripforge.ai/mcp-docs

- `gripforge_style_kit` — resolve "Devil May Cry like" / "genshin" to locker ids
  already tagged with that look. **Call this before generating.** Reuse the ids.
- `gripforge_generate_character` — new T-pose + auto-rig into Library (10 credits).
  `kind=enemy` or the word "enemy" in the prompt. Skip this if style_kit already
  returned a character.
- `gripforge_boss` — playable boss kit (stats, phases, attacks, arena, engine snippets).
  0 credits. Reuses a locker enemy. `generate=true` forges a new kind=enemy (10 credits).
  Then `gripforge_animate` with the returned archetype.
- `gripforge_concept_correct` — concept image → strict T-pose sheet (1 credit).
- `gripforge_attach` — character + prop (paths or Library ids) in, bone-local bind + Three.js / Unity /
  Godot snippets out. Styles: melee, gun, shield, staff (scythe/polearm).
  `attach_id` reuses an armed bind as the character; `prop_id_2` / `prop_path_2` attaches a second
  held item (off-hand). With `export_glb: true` (+ `out_dir`) it also writes `attached.glb`: the
  character with the fist closed and the prop attached, textures preserved —
  use this for mitten-hand rigs, whose closed fist cannot travel in a JSON bind.
- `gripforge_loadout` — multi-weapon character in one call (sets + manifest + clips). 1 credit / prop.
- `gripforge_generate_weapon` — Meshy weapon GLB into Library (kind=weapon, polycount, style=melee|gun). 10 credits. Not generate_character.
- `gripforge_hud` — survivor HUD kit (`hud.json` + PNGs + `.tscn` + snippets). Writes `out_dir` (default `./gripforge-hud`). 1 credit.
- `gripforge_hud_bar` — original themed health-bar frame+fill PNGs. Writes `out_dir`. 2 credits.
- `gripforge_cape` — cape bone grid + skinned `attached_cape.glb` + Godot/Three snippets. Writes `out_dir` (default `./gripforge-cape`). 1 credit.
- `gripforge_formats` — supported formats & options.
- `gripforge_library_list` / `get` / `push` / `pull` / `tag` — the Library locker.
  `kind=animation|audio` is valid. `pull` writes the mesh **and VFX sidecars** (`tex0..png/json`)
  into the open repo (`out_dir`, default `./gripforge-library`).
  Saving a bind after attach is not a second credit.
- `gripforge_audio_kit` — locker SFX + music for a game look. Free.
- `gripforge_animate` — clip pack onto a Mixamo Library char (archetype sword/claws/heavy/brawler/puppet). 0 credits.
- `gripforge_retarget` — clip from skeleton A onto skeleton B.
- `gripforge_rest_pose` — arms-down rest computed against this mesh (weapons stay on an armed bind).
- `gripforge_render` — server PNG preview so the agent can see without a browser.
- `gripforge_scene_kit` — locker props + suggested layout for a game look.
- `gripforge_light_kit` / `gripforge_font` / `gripforge_navmesh` — lights+fog, webfont+ranks, walkable AABB. 0 credits.
- `gripforge_input_kit` — FPS InputMap (WASD + arrows). Write input.json, autoload GfInput.
  Optional `third_person: true` adds portable character-facing JavaScript and a
  Three.js integration example; the existing input map is unchanged. 0 credits.
- `gripforge_viewmodel_kit` — CS-style FPS arms + gun under Camera3D/Hold. Write viewmodel.json + gf_viewmodel.gd. 0 credits.
- `gripforge_loading_page` — overlay html/css/js + Godot/Unity/Unreal. Pass `character_id` for a 16:9 still (1 credit).
- `gripforge_level` — playable room graph from a prompt. 0 credits.
- `gripforge_map_plan` — top-down FPS/bomb map (spawns, sites A/B, lanes, walls). Preview: https://gripforge.ai/map-plan?prompt=dust2. 0 credits.
- `gripforge_map_wires` — sagging electrical spans (2 anchors + sag), not a cable mesh. Pair with map_plan. 0 credits.
- `gripforge_map_look` — still → camera + dressing ids (shot21a A-site). LINK only, never Meshy image-to-3d. 0 credits.
- `gripforge_map_reconstruct` — collect → graph → greybox → zone → camera match → dress. Dust II Valve IP: greybox benchmark only, no BSP. stage=dress = original textures + props + wires. 0 credits.
- `gripforge_hitbox` — body capsules + `weapons[]` from a bind or loadout.
- `gripforge_texture_prep` — local path or `texture_id` → seamless blend + faithful
  lanczos upscale (1×/2×/4×, max 1024 or 2048). Writes the PNG into `out_dir` and
  returns the Library albedo URL. Not a g