# Set up Obelism media for an AI agent

These are the official instructions from Obelism to connect an AI coding agent to media, the file library every Obelism product shares, at https://media.obelism.studio. They are published at `https://media.obelism.studio/agent-setup.md`, so you can check them against that URL at any time.

Do the steps yourself by running the commands and editing the config files directly. Only hand a step to the user where it says so: signing in happens in their browser.

1. Connect the media MCP server
2. Point the agent at the media docs
3. Tell the user what was done

---

## 1. Connect the media MCP server

The server is `https://media.obelism.studio/mcp` (Streamable HTTP). Its tools are the media agent API: list organizations, spaces, folders, files, shares and upload rules, read a file's details, and, with the user's consent, change a file's texts, focal point, tags or folder, add files from a URL, manage folders and create shares.

It signs the user in with OAuth. There is no API key to copy: on first use the client opens media in the browser, the user signs in with their Obelism account and allows the connection. Someone without an account can create one on that same sign-in page.

Use the section for your agent. Register the server globally (for the user), not only for the current project, unless the user asks otherwise. If an entry called `obelism-media` already exists, update it instead of adding a second one, and keep every other setting in the file as it was.

### Claude Code

The Obelism plugin connects media together with Content, Improve and numbers:

```
/plugin marketplace add Obelism/sdk
/plugin install obelism@obelism
```

Or add the server alone:

```
claude mcp add --transport http --scope user obelism-media https://media.obelism.studio/mcp
```

Then tell the user to run `/mcp` inside Claude Code, pick `obelism-media` and choose Authenticate.

### Codex

```
codex mcp add obelism-media --url https://media.obelism.studio/mcp
codex mcp login obelism-media
```

### OpenCode: `~/.config/opencode/opencode.jsonc`

Add under `"mcp"`:

```json
"obelism-media": { "type": "remote", "url": "https://media.obelism.studio/mcp", "enabled": true, "oauth": {} }
```

Then run:

```
opencode mcp auth obelism-media
```

### Cursor: `~/.cursor/mcp.json`

Add under `"mcpServers"`:

```json
"obelism-media": { "url": "https://media.obelism.studio/mcp" }
```

The sign-in starts on the first media tool call, or from Cursor's MCP settings.

### GitHub Copilot in VS Code: `.vscode/mcp.json`, or the user `mcp.json` from "MCP: Open User Configuration"

Add under `"servers"` (VS Code uses `servers`, not `mcpServers`):

```json
"obelism-media": { "type": "http", "url": "https://media.obelism.studio/mcp" }
```

### Windsurf / Devin Desktop: `~/.codeium/windsurf/mcp_config.json`

Add under `"mcpServers"` (note `serverUrl`, not `url`):

```json
"obelism-media": { "serverUrl": "https://media.obelism.studio/mcp" }
```

### Claude (web and desktop) and other apps with connectors

You can't add these yourself. Tell the user to add a custom connector with the URL `https://media.obelism.studio/mcp`.

### Any other MCP client

Register a remote server named `obelism-media` at `https://media.obelism.studio/mcp` with OAuth. The client finds everything else on its own: the server's `401` points to `/.well-known/oauth-protected-resource/mcp`, and clients register with a Client ID Metadata Document or Dynamic Client Registration.

---

## 2. Point the agent at the media docs

media has no skills package. The docs are written for agents instead. Ask the user whether to add this line to the user-level instructions file for your agent, such as `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex, or `~/.config/opencode/AGENTS.md` for OpenCode. Skip this step if they say no.

```
For images, videos and documents in Obelism media (folders, alt text, focal points, shares, Shopify product tags), read https://media.obelism.studio/llms.txt first, and use the obelism-media MCP tools to change them.
```

---

## 3. Tell the user what was done

```
┌─ Obelism media agent setup ──────────────────────────┐
│  ✓ MCP server   <config file or command used>        │
│  ✓ Docs         <instructions file, or skipped>      │
│                                                      │
│  Restart your agent, then sign in to media when      │
│  it opens the browser.                               │
└──────────────────────────────────────────────────────┘
```

If the user wants to show media's files on their site, that is Obelism Content's job: follow https://media.obelism.studio/docs/files/in-content.

---

## Resources

- media MCP server and agent API: `https://media.obelism.studio/docs/agents`
- Docs index for agents: `https://media.obelism.studio/llms.txt`
- OpenAPI spec: `https://media.obelism.studio/openapi.json`
- Claude Code MCP: `https://docs.anthropic.com/en/docs/claude-code/mcp`
- Codex MCP: `https://developers.openai.com/codex/mcp`
- OpenCode MCP: `https://opencode.ai/docs/mcp-servers/`
- Cursor MCP: `https://cursor.com/docs/mcp`
- VS Code MCP: `https://code.visualstudio.com/docs/copilot/customization/mcp-servers`
- Questions: hello@obelism.studio