# Legate Studio — MCP Agent Setup Instructions

## Overview

Legate Studio is a personal knowledge management platform with an MCP-first architecture.
Your notes, categories, assets, and tasks are stored in a private per-user database and
exposed through a standard MCP server.

- **MCP Endpoint**: https://legate.studio/mcp
- **Transport**: streamable-http
- **Auth**: OAuth 2.1 with PKCE (GitHub SSO) — NO API KEY REQUIRED

---

## Prerequisites

1. A Legate Studio account (sign up at https://legate.studio with your GitHub account)
2. An MCP client that supports streamable-http transport and OAuth 2.1

---

## Configuration

### Claude Code (.mcp.json)

Add the following to your `.mcp.json` file in the project root, or to
`~/.claude/mcp.json` for global access:

```json
{
  "mcpServers": {
    "legate": {
      "type": "streamable-http",
      "url": "https://legate.studio/mcp"
    }
  }
}
```

That's it. No API key. No token. No registration flow.

**IMPORTANT: After saving, you MUST restart your Claude Code client for the new
MCP server to load.** Close the session and reopen it — the OAuth flow will
trigger automatically on first connection.

### Claude Desktop (claude_desktop_config.json)

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "legate": {
      "type": "streamable-http",
      "url": "https://legate.studio/mcp"
    }
  }
}
```

**IMPORTANT: Restart Claude Desktop after saving.** The OAuth flow will trigger
automatically on first connection.

---

## Authentication Flow (Automatic)

When your MCP client first connects, it will:

1. Discover the OAuth server at:
   https://legate.studio/.well-known/oauth-authorization-server

2. Open a browser window for GitHub authorization.
   Log in with the GitHub account linked to your Legate Studio account.

3. Return an access token to the client automatically.
   Subsequent requests are authenticated without user interaction.

You will NOT be asked for an API key, a registration token, or any manual
credential configuration. The OAuth flow handles everything.

---

## Verification

After connecting, call the `check_connection` tool to verify:

```
Tool: check_connection
Expected response:
{
  "status": "ok",
  "user": "<your-github-login>",
  "library": "<your-github-login>",
  "message": "Connected to Legate Studio"
}
```

---

## Common First Steps

1. **Explore your library**
   Call `list_categories` to see your knowledge base structure.

2. **Search your notes**
   Call `search_library` with a query string for semantic search.

3. **Create a note**
   Call `create_note` with title, content, and category.

4. **Check recent activity**
   Call `list_recent_notes` to see what was last updated.

---

## Available Tools (47 total)

### Library Management (9 tools)
- search_library        — Semantic search across all notes
- create_note           — Create a new note (syncs to GitHub)
- get_note              — Retrieve a note by title or ID
- get_notes             — List notes in a category or subfolder
- list_categories       — List all categories with note counts
- list_recent_notes     — Most recently created/updated notes
- append_to_note        — Append content to an existing note
- get_related_notes     — Find semantically similar notes
- get_library_stats     — Aggregate stats (notes, categories, assets)

### Note Editing (5 tools)
- update_note           — Replace note content
- rename_note           — Rename a note (updates GitHub path)
- delete_note           — Permanently delete a note
- move_category         — Move a note to a different category
- link_notes            — Create bidirectional links between notes

### Organization (6 tools)
- create_category       — Create a new top-level category
- create_subfolder      — Create a subfolder within a category
- list_subfolders       — List subfolders in a category
- list_subfolder_contents — List notes in a subfolder
- move_to_subfolder     — Move a note into a subfolder
- rename_subfolder      — Rename a subfolder

### Tasks (2 tools)
- list_tasks            — List tasks, filterable by status
- update_task_status    — Update task completion status

### Shared Libraries — managed tier (6 tools)
- create_shared_library — Create a shared library with GitHub repo
- list_libraries        — List personal + all shared libraries
- invite_collaborator   — Invite a GitHub user to collaborate
- accept_invitation     — Accept a library invitation
- remove_collaborator   — Remove a collaborator (owner only)
- sync_shared_library   — Sync library from GitHub (owner only)

### Collaboration — Draft & Merge (6 tools)
- create_draft          — Create a draft note/edit for shared library
- submit_draft          — Submit a draft for owner review
- list_drafts           — List drafts by status/author
- review_draft          — View draft with diff vs original
- merge_draft           — Merge a draft into the library (owner only)
- reject_draft          — Reject a draft with feedback (owner only)

### Advanced (13 tools)
- spawn_agent           — Spawn a background agent task
- process_motif         — Transcribe and structure a voice note
- get_processing_status — Check async job status
- upload_asset          — Upload a binary asset
- list_assets           — List all assets with metadata
- get_asset             — Retrieve an asset by ID
- delete_asset          — Delete an asset
- get_asset_reference   — Get Markdown embed reference for an asset
- upload_markdown_as_note — Create a note from a Markdown file
- check_connection      — Verify connection and identity
- verify_sync_state     — Check DB vs GitHub sync status
- repair_sync_state     — Re-sync library from GitHub
- get_note_context      — Full note context (content + links + related)

---

## Troubleshooting

- **"User not found"**: The GitHub account used for OAuth doesn't have a Legate Studio
  account. Sign up at https://legate.studio first.

- **Tools not appearing**: Ensure `type` is `"streamable-http"` (not `"http"` or `"sse"`).
  Restart the client after editing config.

- **Sync errors**: Call `verify_sync_state`, then `repair_sync_state` to re-sync from GitHub.

---

## Machine-Readable Setup

JSON format: https://legate.studio/docs/mcp/agent-setup.json
Full documentation: https://legate.studio/docs/mcp