Skip to content

Clarify MCP clients and local-model setup #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
VelizarSeleznev wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Clarify MCP clients and local-model setup #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ebb8879
docs: clarify MCP clients and local models
VelizarSeleznev Aug 4, 2026
8452497
docs: sync complete 2.8 MCP registry
VelizarSeleznev Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 11 additions & 8 deletions URL-POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,20 +100,23 @@ Some namespace names do not match their sidebar label — `/auto-mode/*` is labe
"Using Summer". **Leave them.** The label is free to change; the path is not. This
mismatch is a small permanent ugliness and it is the correct trade.

## Generated pages
## Generated-page targets

Some pages are generated from source and must not be hand-edited. They carry a
banner saying so. Editing them by hand produces a change that is silently reverted on
the next generation, and worse, a page that disagrees with what actually ships.
Some reference pages are intended to be generated from product source. A page
is actually generated only when its frontmatter contains `generated: true` and
names its `generator`; those pages must not be hand-edited. The checker enforces
that contract. Pages without that marker remain checked-in documentation and
must be updated from the owning source plus their repository checks until their
generator exists.

Generated pages publish to their existing frozen URLs rather than to a new
`/reference/*` namespace, for the reason this whole document exists:

| Page | Generated from |
| Page | Current source contract |
|---|---|
| `/ai-tools/operations` | The engine's unified operation registry |
| `/mcp/tools-reference` | The MCP server's tool definitions |
| `/mcp/cli-reference` | The CLI's command definitions |
| `/ai-tools/operations` | Keep aligned with the engine's unified operation registry until a generator is attached. |
| `/mcp/tools-reference` | Keep aligned with the canonical MCP server definitions; `npm run check:mcp-registry` verifies the complete 2.8 inventory. |
| `/mcp/cli-reference` | Keep aligned with the CLI command definitions until a generator is attached. |

If a generated page is wrong, fix the source. Never the page.

Expand Down
183 changes: 91 additions & 92 deletions mcp/antigravity.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,142 +1,141 @@
---
title: "Build Games in Antigravity with Summer Engine MCP"
description: "Connect Summer Engine's MCP server to Antigravity and build games with Google's AI-powered IDE driving your engine."
description: "Set up Summer Engine in Antigravity's current native MCP and Agent Skills directories without changing your model."
icon: "rocket"
---

{/* Do not reintroduce a hardcoded MCP tool count here. The tool list grows every release and a baked-in number has already gone stale twice. */}

## Summer Engine in Antigravity

Antigravity is Google's AI-powered IDE that supports MCP (Model Context Protocol). With Summer Engine's integration, Antigravity's AI can control your game engine: add nodes to scenes, set properties, import assets, run the game, and debug, all from within your coding workflow.

This guide covers the configuration. Setup takes about a minute.
Antigravity is the MCP client. Its selected Google or third-party model is a
separate setting; Summer setup does not change that model or provider.

## Prerequisites

- **Antigravity**: Google's AI-powered IDE
- **Node.js**: For running the MCP server (Node 18+)
- **Summer Engine**: Installed and running with your project open
- **Antigravity**
- **Node.js 18+**
- **A Summer Engine project** open in Summer Engine

## Configuration
## One-command project setup

Antigravity uses the VS Code MCP config format. The config file is:
Update the terminal client first, then open a terminal in the project:

- **Project-level:** `.vscode/mcp.json` in your project root
- **Global:** Use the Antigravity CLI (`antigravity --add-mcp`) if available
```bash
agy update
```

<Note>
**Config format.** Antigravity uses `servers` (not `mcpServers`). The structure matches VS Code's MCP configuration.
</Note>
Open a terminal in the project and run:

### Step 1: Create or Edit the Config File
```bash
npx -y summer-engine@latest setup antigravity --yes --force --project "$PWD"
```

Create `.vscode/mcp.json` in your project root. If the file already exists (e.g., for other MCP servers), add Summer Engine to the existing `servers` object.
This creates or merges:

### Step 2: Add Summer Engine
- `.agents/mcp_config.json` with the `summer-engine` MCP server
- `.agents/skills/<skill>/SKILL.md` with recommended Summer guidance

<CodeGroup>
It preserves other MCP servers and unrelated JSON keys. The generated MCP
command is bound to the absolute project path, so it does not guess when more
than one Summer editor is open.

```json New file (.vscode/mcp.json)
{
"servers": {
"summer-engine": {
"command": "npx",
"args": ["summer-engine", "mcp"]
}
}
}
```
<Note>
Current Antigravity uses `.agents/mcp_config.json` with a top-level
`mcpServers` object. Older instructions that use `.vscode/mcp.json` and
`servers` describe a legacy compatibility path.
</Note>

For a global setup, run without `--project` and add `--scope user`. The
global files live under `~/.gemini/config/mcp_config.json` and
`~/.gemini/config/skills/`.

```json Adding to existing servers
## Manual configuration

```json .agents/mcp_config.json
{
"servers": {
"other-server": { ... },
"mcpServers": {
"summer-engine": {
"command": "npx",
"args": ["summer-engine", "mcp"]
"args": [
"-y",
"summer-engine@latest",
"mcp",
"--project",
"/absolute/path/to/your/project"
]
}
}
}
```

</CodeGroup>

### Step 3: Restart Antigravity

Close and reopen Antigravity so it loads the new MCP config. The Summer Engine MCP server starts when Antigravity starts; it connects to the engine on the first tool call.

### Step 4: Verify

Check Antigravity's MCP or AI settings to confirm "summer-engine" appears and its tools are listed. Then try a prompt:
## Reload and verify

- "Use Summer Engine to add a MeshInstance3D with a BoxMesh to the scene"
In the desktop app, open **Settings > Customizations > MCP Servers**. In the
terminal client, start `agy` from the configured project and run `/mcp`.

If the node appears in Summer Engine, the setup is working.
1. Refresh or restart `summer-engine` and inspect its connection status.
2. Confirm the host itself lists the Summer tools; `doctor` only proves the
server can register them.
3. Keep MCP tools in **Ask** mode for the first test.
4. Start a fresh conversation in the configured project and paste:

## Using Summer Engine with Antigravity
```text
Use the summer-engine MCP server. Call summer_get_agent_playbook and read its
result. Then call summer_get_project_context and summer_get_scene_tree. Report
the exact project and scene you found. Do not change anything. If a call fails,
quote the error and stop.
```

Once configured, the AI can use Summer Engine's tools when you ask for game-related changes. Example prompts:
Only proceed to mutations when the model discovers the server, calls a tool,
consumes its result, and reports the correct project identity.

- "Add a Camera3D and DirectionalLight3D to the scene root"
- "Get the scene tree from Summer Engine"
- "Import this model and add it to the World node: [URL]"
- "Run the game and capture a screenshot"
- "Set the project's main scene to res://main.tscn"
<Note>
In our `agy` 1.1.10 interactive smoke, the project-scoped server called and
consumed the playbook, project context, and scene tree, then added and saved a
node, read it back, removed and saved it, and confirmed the clean final tree.
</Note>

<Tip>
**Engine must be running.** Antigravity's AI talks to Summer Engine over localhost. Open your project in the engine first, or run `npx summer-engine run` from the project directory.
</Tip>
<Warning>
Do not use `agy -p` (headless print mode) as the MCP readiness check in that
build. It rejected the same working project server with
`tool ... is not enabled for server summer-engine`, while a normal interactive
`agy` session succeeded. If that error appears under `-p`, start `agy` normally
in the configured project, run `/mcp`, and test in a fresh conversation. Stop
before mutations only if the normal interactive session also rejects the call.
</Warning>

## Troubleshooting

### "Summer Engine is not running"
### Server does not appear

Start Summer Engine and open your project. The MCP server connects to the engine's local API on port 6550. The engine writes a token to `~/.summer/api-token` when it starts.
- Confirm the opened project contains `.agents/mcp_config.json`.
- Open **Customizations > MCP Servers**, refresh, and inspect the connection
log instead of repeatedly restarting.
- Run `npx -y summer-engine@latest doctor --json` in the project.

### MCP server not appearing
### Summer Engine is not running

- **Config path:** Verify `.vscode/mcp.json` is in your project root (the folder you opened in Antigravity)
- **JSON validity:** Ensure no trailing commas, proper quotes, and valid JSON structure
- **Restart:** Fully quit and reopen Antigravity
Open the same project in Summer Engine. The MCP process discovers the matching
local editor instance on its first tool call.

### Tools return errors
### Tools are listed but the model does not call them

See the [Tools Reference](/mcp/tools-reference) for parameter formats. Common issues: wrong node path format (`./World/Player`), invalid property values (use engine string format like `"Vector3(0, 10, 0)"`), or the game running when scene edits are attempted (stop it first with `summer_stop`).
Start a fresh conversation, use a model trained for multi-turn tool calling,
give it at least 64k context, and require the read-only playbook/context test
above. Tool visibility alone does not prove the model can consume tool results.

## Next Steps
## Next steps

<CardGroup cols={2}>
<Card
title="Tools Reference"
icon="wrench"
href="/mcp/tools-reference"
>
Every MCP tool with parameters and examples
<Card title="MCP Setup Overview" icon="plug" href="/mcp/setup">
Client/provider choices and supported setup targets
</Card>
<Card
title="Building a Game"
icon="gamepad-2"
href="/mcp/building-a-game"
>
How an AI builds a full game using MCP
<Card title="Tools Reference" icon="wrench" href="/mcp/tools-reference">
MCP tools and parameter formats
</Card>
<Card
title="MCP Setup Overview"
icon="plug"
href="/mcp/setup"
>
Architecture, prerequisites, and other IDEs
<Card title="Local Models" icon="microchip" href="/mcp/local-models">
Use LM Studio, OpenCode, Ollama, or Goose with the same MCP server
</Card>
<Card
title="CLI Reference"
icon="terminal"
href="/mcp/cli-reference"
>
summer install, run, create, and more
<Card title="Building a Game" icon="gamepad-2" href="/mcp/building-a-game">
Move from read-only verification to a real project
</Card>
</CardGroup>

---

Need help or have questions? Reach out to our founders at [founders@summerengine.com](mailto:founders@summerengine.com) or join our community on [Discord](https://discord.gg/yUpgtxnZky) for fast responses.
51 changes: 41 additions & 10 deletions mcp/local-models.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,58 @@ icon: "microchip"

You don't need an AI subscription to build games in Summer Engine. Any local model that handles tool calling can drive the engine through MCP: add nodes, set properties, search and import assets, run the game, and debug. Engine control and asset search are free; cloud generation (3D models, images, audio) uses credits.

This page covers the three setups that actually work in 2026.
First choose an MCP client. Then choose the model runtime/provider. They are
independent layers:

| MCP client | Model runtime/provider | Setup status |
|---|---|---|
| LM Studio chat | LM Studio | Direct CLI-managed MCP setup |
| OpenCode | Any existing provider | CLI-managed, provider-neutral MCP setup |
| OpenCode | LM Studio | Explicit combined recipe |
| OpenCode or Kilo Code | Ollama | MCP setup is managed; provider setup remains client-owned |
| Goose | Ollama or another provider | Manual MCP extension setup |

## Prerequisites

- **A GPU with 12 GB+ of VRAM** (or Apple Silicon with 16 GB+ unified memory). 24 GB is the sweet spot.
- **Node.js**: For running the MCP server (Node 18+)
- **Summer Engine**: Installed and running with your project open

## Option 1: LM Studio (easiest)
## Option 1: LM Studio directly

LM Studio is both the model runtime and an MCP host. One terminal command writes
the integration; the actual model chat and tool calls then stay inside LM Studio.

LM Studio is both the model runtime and an MCP host — one app, no terminal.
LM Studio Chat cannot run the installer for you. Do not paste the coding-agent
setup prompt into the model and expect it to edit its own MCP file. Run the
following command yourself in a normal terminal, or use LM Studio's in-app
**Edit mcp.json** action and merge the manual entry.

```bash
npx -y summer-engine@latest setup lm-studio --yes
npx -y summer-engine@latest setup lm-studio --yes --project "/absolute/path/to/project"
```

This writes the `summer-engine` server into `~/.lmstudio/mcp.json`. Then, in LM Studio:
This updates the active LM Studio MCP config, preserves other servers, binds
Summer to the named project, and exposes the same complete Summer MCP tool
registry used by other clients. It does not require OpenCode. LM Studio has
changed config paths between releases; use **Edit mcp.json** inside LM Studio
as the source of truth rather than assuming `~/.lmstudio/mcp.json`.

Then, in LM Studio:

1. Download a model in the **Discover** tab (see [model picks](#which-model-to-run) below).
2. Toggle the `summer-engine` MCP server on in the **Program** tab.
3. **Raise the model's context length to 32k or higher** when loading it. Models load with the context baked into their metadata — often ~4k, which MCP tool schemas overflow silently.
2. Toggle `summer-engine` under **Chat > Integrations** (**Program** in older versions).
3. Use a multi-turn tool-calling model with **64k context or more**.
4. Keep KV-cache quantization off for long agent sessions. On Apple Silicon, prefer the MLX builds.

Every engine call shows a confirmation dialog you can review before it runs.

Start with `summer_get_agent_playbook`, project context, and scene tree without
mutating anything. A model that emits a tool call but cannot consume its result
is not safe for scene edits. If LM Studio reports Jinja errors such as
`Unknown ArrayValue filter: upper` or `Unknown test: sequence`, fix or replace
the model's prompt template; reducing the tool count alone does not repair it.

## Option 2: OpenCode + Ollama (terminal)

The most common pairing in 2026. Ollama serves the model; OpenCode is the agent.
Expand All @@ -46,10 +73,12 @@ OLLAMA_CONTEXT_LENGTH=65536 ollama serve
ollama pull qwen3-coder:30b

# 3. Wire Summer Engine into OpenCode
npx -y summer-engine@latest setup opencode --yes
npx -y summer-engine@latest setup opencode --yes --project "$PWD"
```

Then point OpenCode's provider at Ollama (`http://localhost:11434/v1` as an OpenAI-compatible endpoint) and select your model. Run `ollama ps` to confirm the bigger context hasn't pushed the model off the GPU.
This command changes only OpenCode's Summer MCP entry and guidance. Configure
the Ollama provider in OpenCode separately, then run `ollama ps` to confirm the
bigger context has not pushed the model off the GPU.

The same Ollama backend works with **Kilo Code** in VS Code (`npx -y summer-engine@latest setup kilo-code --yes`) — set the context window to 32k+ in Kilo's provider settings.

Expand Down Expand Up @@ -89,4 +118,6 @@ Tool calling is the hard part for local models. Use Q4_K_M quantization or bette
| Asset library search (25k+ assets) | **Free**, rate-limited |
| Cloud generation (3D, image, audio, video) | Credits |

Sign in once with `npx summer-engine login` — the account is the rate-limit key, not a paywall.
Local engine control does not require signing in. Sign in with
`npx -y summer-engine@latest login` only when you want account-backed asset
search or cloud generation; cloud generation uses credits.
Loading
Loading