# Connect Mosyn: guide for AI agents

Mosyn is an Android study app with a remote MCP server. Once connected, you can create study sets and cards for the person, attach pictures and audio, and write custom study games; everything you write appears on their phone as you write it. The person approves the connection in the Mosyn app on their phone. No API key, header or password is involved.

## 1. Check the prerequisite

Ask the person to confirm that the Mosyn app is installed on their Android phone and signed in. They approve the connection there, so it must be ready before you start.

If it isn't, send them to https://mosyn.lycatra.com/download and wait until they've installed it and signed in. Mosyn is Android only.

## 2. The MCP URL

```text
https://mosyn.lycatra.com/mcp
```

Transport: Streamable HTTP. Auth: OAuth 2.1 with PKCE and dynamic client registration; the client registers itself.

## 3. Add Mosyn to the client you're running in

Run the command for your client:

- Claude Code:

```sh
claude mcp add --transport http --scope user mosyn https://mosyn.lycatra.com/mcp
```

- OpenAI Codex:

```sh
codex mcp add mosyn --url https://mosyn.lycatra.com/mcp
```

- Gemini CLI:

```sh
gemini mcp add --transport http --scope user mosyn https://mosyn.lycatra.com/mcp
```

- Devin Desktop:

```sh
devin mcp add -s user mosyn https://mosyn.lycatra.com/mcp
```

- VS Code (GitHub Copilot):

```sh
code --add-mcp '{"name":"mosyn","type":"http","url":"https://mosyn.lycatra.com/mcp"}'
```

- OpenCode: add this to `~/.config/opencode/opencode.json, or opencode.json in a project`, then run `opencode mcp auth mosyn`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mosyn": {
      "type": "remote",
      "url": "https://mosyn.lycatra.com/mcp",
      "enabled": true
    }
  }
}
```

- Cursor: add this to `~/.cursor/mcp.json, or .cursor/mcp.json in a project`:

```json
{
  "mcpServers": {
    "mosyn": {
      "url": "https://mosyn.lycatra.com/mcp"
    }
  }
}
```

- goose: add this to `~/.config/goose/config.yaml`, or run `goose configure`:

```yaml
extensions:
  mosyn:
    name: Mosyn
    type: streamable_http
    uri: https://mosyn.lycatra.com/mcp
    enabled: true
    timeout: 300
```

- Any client that only runs local (stdio) servers: use the mcp-remote bridge (Node.js 18+):

```sh
npx -y mcp-remote https://mosyn.lycatra.com/mcp
```

Web and phone assistants can't be configured by you. Give the person the link or steps instead:

- Claude (claude.ai, desktop, mobile): send the person this link. It opens Claude's Add custom connector dialog with Mosyn filled in; they click Add, then Connect: https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Mosyn&connectorUrl=https%3A%2F%2Fmosyn.lycatra.com%2Fmcp
- ChatGPT: Creating sets and cards is confirmed on Business, Enterprise and Edu, where an admin may first have to allow custom MCP servers. On Plus and Pro, ChatGPT may only read. Guide: https://mosyn.lycatra.com/connect/chatgpt
- Anything else: https://mosyn.lycatra.com/connect lists every assistant, with Markdown at https://mosyn.lycatra.com/connect/<client>.md.

## 4. Relay the authorization URL

Adding Mosyn starts an OAuth sign-in. When your client prints or opens an authorization URL, give it to the person as a clickable link and tell them what happens next:

> A browser page from Mosyn opens with an eight-character code and a QR code. Open the Mosyn app on your phone and approve the request there (scan the QR code, tap the link on the phone, or type the code in Settings → Connect an assistant → Have a code?).

Then wait for them to say they approved it. If your client needs a separate login step (for example `claude mcp login mosyn`, `codex mcp login mosyn`, `opencode mcp auth mosyn`, or `/mcp` then Authenticate), run it.

**Never ask the person for a code, password or token in chat, and never paste the connection code into a tool call.** The code is typed only into the Mosyn app on their phone.

## 5. Verify

Call the `list_sets` tool. Any successful result means Mosyn is connected; an empty list is success for a new account. Tell the person it worked, then ask what they'd like to study.

## 6. If something goes wrong

| Symptom | What to do |
| --- | --- |
| 401, “Needs authentication”, or “not logged in” | Run your client's login command again (see step 4) and relay the new authorization URL. |
| `AUTHORIZATION_EXPIRED`, or the page says the request expired | Start again. The person has ten minutes to approve in the app. |
| The person sees nothing on their phone | Make sure the Mosyn app is installed (https://mosyn.lycatra.com/download) and signed in, then approve by scanning the QR code or typing the code in the app (Settings → Connect an assistant → Have a code?). Cards you create appear once the app is open and online. |
| A free-plan limit is reached | Tell the person which limit was reached. Don't mention prices or buying, and don't send purchase links; the person manages their plan in the Mosyn app. |
| The tool list is empty, or Mosyn tools disappeared | The grant was revoked or expired. Remove Mosyn from the client, add it again, and relay the new authorization URL. |
| Any other error | Error messages from Mosyn say what to do next; follow them. If stuck, point the person to the setup guide for their client. |

## More

- Per-client guides: https://mosyn.lycatra.com/connect (Markdown: https://mosyn.lycatra.com/connect.md)
- Tools and limits: https://mosyn.lycatra.com/docs (Markdown: https://mosyn.lycatra.com/docs.md)
- Support: mosyn@lycatra.com
