---
title: "VS Code Copilot and the iOS simulator: MCP setup | Mobster"
description: "Add Mobster's MCP server to VS Code for GitHub Copilot's agent mode, in the portable .mcp.json or .vscode/mcp.json, and check iOS screens on a simulator."
canonical: "https://mobster.dev/integrations/vs-code"
last-updated: "2026-10-08"
---

Add Mobster's MCP server to VS Code for GitHub Copilot's agent mode, in the portable .mcp.json or .vscode/mcp.json, and check iOS screens on a simulator.

# VS Code Copilot and the iOS simulator: MCP setup

Add Mobster's MCP server to VS Code for GitHub Copilot's agent mode, in the portable .mcp.json or .vscode/mcp.json, and check iOS screens on a simulator.

## The short version

Install Mobster CLI, then run:

```
code --add-mcp "{\"name\":\"mobster\",\"command\":\"mobster\",\"args\":[\"mcp\"]}"
```

Config file: .mcp.json at the workspace root, or ~/.copilot/mcp-config.json

**From the docs.** This setup follows Microsoft's MCP documentation, read on 8 October 2026. Mobster's MCP server is tested with Claude Code; we haven't run it in VS Code ourselves yet. [Microsoft’s MCP docs](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

GitHub Copilot’s agent mode in VS Code can edit your SwiftUI views, but it can’t see the simulator. Add `mobster mcp` and Copilot gets tools to run your app on a headless iOS simulator, read each screen as a list of controls by name, tap and type, and finish with a verdict of passed or failed from assertions on the accessibility tree. The same server can drive a real iPhone plugged into your Mac.

You need an Apple silicon Mac with macOS 15 or later and Xcode with an iOS Simulator runtime. A real iPhone also needs Developer Mode and the WebDriverAgent runner, set up in Mobster for Mac or with `mobster serve --manage-device` ([Device setup](https://docs.mobster.dev/device-setup)).

## Install Mobster CLI

```
curl -fsSL https://mobster.dev/install.sh | sh
```

or

```
brew install radishsoftware/tap/mobster
```

```
mobster version
which mobster
mobster sim doctor --fix
```

The last command creates Mobster’s simulator, boots it headless and builds WebDriverAgent once per Xcode version, so Copilot’s first check starts warm.

## Add the server

VS Code reads two formats, and they differ in one word. Get the word wrong and the server never loads.

The portable format, which the MCP: Add Server command now prefers, goes in `.mcp.json` at the workspace root (for the project) or `~/.copilot/mcp-config.json` (for you), under `mcpServers`:

```
{  "mcpServers": {    "mobster": {      "type": "stdio",      "command": "mobster",      "args": ["mcp"]    }  }}
```

The VS Code format goes in `.vscode/mcp.json` or your user profile, under `servers`. It still works, and the Add Server flow lists it as deprecated:

```
{  "servers": {    "mobster": {      "type": "stdio",      "command": "mobster",      "args": ["mcp"]    }  }}
```

VS Code’s field table marks `type` as required for a local server while its examples leave it out, so both blocks include it. From a terminal, this adds the server to your user profile:

```
code --add-mcp "{\"name\":\"mobster\",\"command\":\"mobster\",\"args\":[\"mcp\"]}"
```

VS Code’s docs say `command` must be on the system path or a full path. If the server doesn’t start, replace `mobster` with the output of `which mobster`.

For Smart, where Mobster runs the steps itself on your OpenAI or Anthropic key, add `"--env-file", "~/.config/mobster/agent.env"` after `"mcp"` in `args`. Mobster expands the `~`. Key-less checks, where Copilot drives, need no key.

VS Code’s MCP pages don’t document a tool-call timeout. Mobster doesn’t rely on one: every call returns within 45 seconds and `wait` within 50, and slow work such as the first simulator boot continues under a `run_id` that Copilot polls with `wait`.

## Check it’s connected

Run MCP: List Servers from the Command Palette. mobster should be running, and Show Output there has its log. A workspace server inherits Workspace Trust; a server from another source shows a trust dialog the first time it starts. Then ask Copilot in agent mode:

```
Call mobster's status tool and tell me what it says.
```

## A first check: choosing a plan

Daybreak, the sample app in the CLI’s repository, has a paywall with three plan cards. Annual starts selected. A prompt that exercises a tap and a state change:

```
Build Daybreak for the simulator and verify that tapping the Monthly plan
on the paywall (daybreak://paywall) makes Monthly the selected plan.
```

Copilot calls `verify_start` with the absolute `app_path`, `open_url` set to `daybreak://paywall`, the step, and an expectation it can’t meet before the tap, such as:

```
{"visible": {"id": "plan_monthly", "selected": true}}
```

Then it reads the screen and taps by identifier:

```
{"tool": "tap", "arguments": {"run_id": "…", "target": {"id": "plan_monthly"}}}
```

On 28 Sep 2026 that tap answered `Tapped “Monthly”; the screen changed.`, and the new outline had `selected` on Monthly. `verify_finish` then checks the expectation on a settled read and returns the verdict, the report path and the overlay frame. Writing an expectation that only holds after the steps matters: if it already held at launch, the run ends `needs_review`, because it wouldn’t show the tap did anything. [AI end-to-end tests for iOS](https://mobster.dev/blog/ai-e2e-tests-ios-assertions) explains that rule.

## Tell Copilot to verify every change

VS Code’s docs list `.github/copilot-instructions.md` or `AGENTS.md` as the project instruction files for the Copilot agent. Add:

```
## Verifying UI changesAfter you change a screen in this iOS app, verify it before you say it works.1. Build for the simulator:   xcodebuild -scheme <Scheme> -destination 'generic/platform=iOS Simulator' -derivedDataPath .mobster/build CODE_SIGNING_ALLOWED=NO build2. Call mobster's verify_start with app_path set to the absolute path of   .mobster/build/Build/Products/Debug-iphonesimulator/<App>.app, the steps in plain English, and expect:   what must be true when the steps are done.3. Drive with screen, tap, type_text and swipe, then call verify_finish.4. If the verdict is failed, fix the code and verify again. Report the verdict and the report path.
```

## Use a real iPhone

`list_devices` shows every device Mobster can use. With a USB iPhone’s name as `device` and no `run_id`, `screen`, `tap`, `type_text`, `swipe`, `alert`, `open_url`, `launch_app` and `home` drive the phone directly. Mobster holds the phone’s lock until `stop` with the `device`, or 90 idle seconds.

VS Code asks before a tool runs, and lets you approve a single use, the session, the workspace or every future call. “Chat: Manage Tool Approval” can trust every tool from one server. Be careful with both on a server that can reach your phone: an approval covers a tool, not a device, so trusting `tap` for simulator work trusts it on your iPhone. Keep the server to the phones you choose:

```
"args": ["mcp", "--allow-device", "Test iPhone"]
```

Mobster’s MCP annotations mark `status`, `screen`, `list_devices`, `wait`, `wait_for`, `read_notifications` and `unlock_status` as read-only and the rest as acting, and its instructions tell the agent to ask you before anything that sends, buys, posts or deletes on a real iPhone. A locked phone stops the call at once with “Your iPhone is locked. Unlock it and try again. No action was taken.”

## Troubleshooting

| Symptom | Fix |
|---|---|
| The server never appears | Check the top-level key: `servers` in `.vscode/mcp.json`, `mcpServers` in `.mcp.json` and `~/.copilot/mcp-config.json` |
| It appears but won’t start | Use the full path from `which mobster` in `command`, then restart it from MCP: List Servers |
| Copilot says too many tools are enabled | One request can use at most 128 tools. Turn off the tools or servers you don’t need for that chat |
| The first `verify_start` returns `status: "preparing"` | The simulator is booting and WebDriverAgent is building. Copilot calls `wait`, or run `mobster sim doctor --fix` first |
| `couldnt_run` | `reason.class` and `reason.fix` in the result say what to do ([Checks](https://docs.mobster.dev/checks)) |

Every tool is in the [MCP reference](https://docs.mobster.dev/mcp-server).

## Questions

- ### Should Mobster go in .vscode/mcp.json or .mcp.json?
  Either works. VS Code's MCP: Add Server flow now prefers the portable .mcp.json at the workspace root, or ~/.copilot/mcp-config.json for your user, and labels .vscode/mcp.json deprecated. The two formats use different top-level keys, servers in .vscode/mcp.json and mcpServers in the portable files.
- ### Does Mobster fit under VS Code's tool limit?
  VS Code allows at most 128 tools in one chat request. Mobster's server offers about two dozen, so it fits beside other servers. If a chat hits the limit, turn off the tools you don't need for it.
- ### Where do I tell Copilot to verify UI changes?
  In .github/copilot-instructions.md or AGENTS.md, which VS Code's docs list as the project instruction files for the Copilot agent.

## Sources

We read each of these on 8 October 2026. Reviewed by Andy Guo on 8 October 2026. Corrections are welcome at the [GitHub repo](https://github.com/RadishSoftware/mobster/issues).

- [VS Code docs: add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
- [VS Code docs: MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
- [VS Code docs: use tools in chat (128 tools per request)](https://code.visualstudio.com/docs/agents/run/tools)
- [VS Code docs: approvals and permissions](https://code.visualstudio.com/docs/agents/run/approvals)
- [VS Code docs: trust and safety](https://code.visualstudio.com/docs/agents/concepts/trust-and-safety)
- [VS Code docs: custom instructions](https://code.visualstudio.com/docs/agent-customization/custom-instructions)
- [MCP specification: ToolAnnotations (readOnlyHint)](https://modelcontextprotocol.io/specification/2025-11-25/schema)
- [Mobster docs: MCP server](https://docs.mobster.dev/mcp-server)
- [Mobster docs: checks](https://docs.mobster.dev/checks)
- [Mobster docs: device setup](https://docs.mobster.dev/device-setup)

VS Code’s logo is a trademark of Microsoft, shown only to name the product. Mobster isn’t affiliated with or endorsed by Microsoft.

## Read next

- [Every MCP tool, in the reference](https://docs.mobster.dev/mcp-server)
- [Getting started with verify](https://docs.mobster.dev/verify)

## Other agents

- [Claude Code](https://mobster.dev/integrations/claude-code)
- [Codex](https://mobster.dev/integrations/codex)
- [Cursor](https://mobster.dev/integrations/cursor)
- [Claude Desktop](https://mobster.dev/integrations/claude-desktop)
- [Gemini CLI](https://mobster.dev/integrations/gemini-cli)
- [opencode](https://mobster.dev/integrations/opencode)
- [Windsurf (Devin Desktop)](https://mobster.dev/integrations/windsurf)