# Muse Code

Connect Muse Code, Meta's terminal coding agent, to XMemo through OAuth with one mcpServers entry in ~/.config/muse/settings.json.

- Canonical: https://docs.xmemo.dev/docs/mcp/muse-code
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: c631844310ded8cc16c2cad894551ed2d09965b65311a9761a503f7d931352f8
- Edition-Digest: 3c9a08e9bc98e5c5eb95238df71c162805a4244379aab1b24a21a86ea8f67cd0
- Source-Revision: sha256:e4bb1025634b1d0521ab71134877bf1e2b23afe54bf4b03acb52c414a035e7f5

## Prerequisite

Use a Muse Code install that reads MCP servers from ~/.config/muse/settings.json. Muse Code connects to XMemo as an OAuth client, so the config file holds no token.

- Endpoint: https://xmemo.dev/mcp.
- Auth mode: OAuth (browser PKCE) with dynamic client registration.
- Config file: ~/.config/muse/settings.json. It must contain "schema_version": 1.
- Granted scopes: memory:read, memory:write, knowledge:read and knowledge:write.
- Automated setup: xmemo setup muse-code is coming soon with the next XMemo CLI release. Until then, use the manual config below.

## Add XMemo to settings.json

Edit ~/.config/muse/settings.json from a terminal outside Muse; Muse's sandbox rejects edits to this file made inside a Muse session. Add an xmemo entry under the top-level camelCase mcpServers key. No token or Authorization header belongs in this file.

```json
{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}
```

## Keep only mcpServers

Muse's public web docs still show a snake_case mcp_servers key, which is stale. If settings.json contains both mcpServers and mcp_servers, Muse drops every MCP server. Rename an existing mcp_servers block to mcpServers and merge its entries into it, so the file keeps only mcpServers.

## Sign in with OAuth

Run the login command for the xmemo server and approve access in the browser. On a machine without a browser UI, add --headless.

```bash
muse mcp login xmemo
# Without a browser UI:
muse mcp login xmemo --headless
```

## Restart the client

Restart Muse after signing in so it loads the xmemo server with the new OAuth grant.

## Verify the XMemo tools

Ask Muse to list the XMemo tools without calling any of them.

```bash
muse exec "List the names of the tools you have from the xmemo MCP server. Do not call any tools."
```

## Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

```text
recall({ query: "connection check", limit: 1 })
```

## Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## XMemo Skill

Muse scans ~/.agents/skills, ~/.claude/skills and ~/.codex/skills, so an XMemo Skill already installed for Claude Code or Codex works in Muse without changes.

## Common Errors

Muse Code connects through OAuth; most errors come from the config key, the sign-in step or the sandbox.

- No xmemo tools are listed: settings.json contains both mcpServers and mcp_servers, so Muse dropped every MCP server. Keep only mcpServers.
- invalid_grant: the authorization is invalid, expired or already used, or the selected connection is no longer valid. Run muse mcp login xmemo again, then restart Muse.
- 403 insufficient_scope: the approved scopes do not cover the call. Sign in again and approve the memory and knowledge scopes.
- Edits to settings.json are rejected: the change was made inside a Muse session. Edit the file from an outside terminal.

## Muse Code

OAuth client: add xmemo under mcpServers in ~/.config/muse/settings.json, then run muse mcp login xmemo and restart Muse. No token goes in the config. Keep only mcpServers: if mcp_servers is also present, Muse drops every MCP server.

```
{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}
```