# Superself connection guide

Superself keeps a project's context — decisions, current state, knowledge —
in one place (superselfs.com), so every AI session starts from the current
truth instead of a re-explanation. Once connected, you (the agent) can open
the user's project with `session_open`, read its knowledge, and write back
what changed — across Claude, ChatGPT, Codex, and any MCP-capable client.

This guide is written for an agent (you) to read and follow. Before the
steps, tell your human in a sentence or two what they get — for example:
"Superself keeps your project's context in one place, so any AI session can
pick up where the last one left off. I can set up the connection; the only
part you do yourself is a Google sign-in." Then follow the section for your
client. The sign-in and consent screen is the human's step everywhere: open
it, hand it over, and continue once they've approved.

(Superself is run by Superfunction, contact hello@fxy.global. The Claude Code
plugin's source is public at https://github.com/spfn/plugin. Common questions
about access and tokens are answered in "Good to know" at the end.)

## Which client are you?

- **Claude Code (terminal CLI)** — follow "Claude Code plugin" below. You can
  run every command yourself; the sign-in browser window is the human's part.
- **ChatGPT (web)** — connector settings are outside the chat, so guide your
  human through "ChatGPT connector" below, then verify.
- **Claude web / Claude desktop** — same: guide your human through "Claude
  web · Claude desktop connector" below, then verify.
- **Codex** — follow the exact CLI flow in "Codex" below. Keep the add
  command running through browser approval; its final output is the login
  result.
- **Another MCP-capable client** — follow "Other MCP clients" below.

Whatever the client: setup is complete when the first `session_open` returns
the project the human intends to use.

## Claude Code plugin

Run the commands below in order, compare the output against what's expected,
and only move to the next step once it matches. If the output differs, check
that step's self-diagnosis block first. If you're still stuck, see the
contact at the end.

### 1. Check prerequisites

Confirm Claude Code is installed and you're logged in.

```
claude --version
```

A version string (e.g. `1.x.x (Claude Code)`) means it's installed. You don't
need to check login separately — later (step 4), Claude Code will open the
login/authorization flow automatically the moment it's needed.

**If you don't see this →**
- `command not found` — Claude Code isn't installed. Follow the instructions
  at https://claude.com/claude-code and try again.
- Version prints but looks unusually old — run `claude update` (optional, not
  required to continue).

### 2. Add the marketplace

```
claude plugin marketplace add https://superselfs.com/marketplace.json
```

You should see a confirmation that the marketplace `superself` was added.

**If you don't see this →**
- `404` or a fetch failure — double-check the URL for typos, and check for a
  network/proxy block.
- An "already exists" style message — the marketplace was already added.
  That's not an error; continue to step 3.

### 3. Install the plugin

```
claude plugin install fxy@superself
```

You should see a confirmation that the `fxy` plugin was installed.

**If you don't see this →**
- Install failure / source unreachable — the marketplace points at the
  GitHub repo `spfn/plugin` at a fixed version tag; that repo may be
  temporarily unreachable. Retry shortly, or re-check step 2.
- The version shown looks wrong — the marketplace metadata may be stale. Run
  `claude plugin marketplace update superself` and reinstall.

### 4. Connect MCP (OAuth)

After installing the plugin, start a new session and the superself MCP
server (`https://superselfs.com/mcp`) will show up in the connection list.
The first time a tool on that server is called, the server returns a 401 and
Claude Code automatically opens a browser to the Superself authorization page
(Google sign-in, then a consent screen). Once a human approves there, a token
is stored locally, and it's attached to every request from then on.

Check that the connection completed with:

```
claude mcp list
```

or, inside a session, the `/mcp` slash command. If `superself` shows as
connected, this step is done.

**If you don't see this →**
- 401 keeps repeating — the browser callback arrives on a temporary localhost
  port, which may be blocked by a firewall or popup blocker. Confirm the
  authorization page actually opened in a browser and that approval was
  clicked.
- No browser available (e.g. SSH) — this isn't supported yet. For now,
  complete the install on a machine with a local browser first.

### 5. Verify it works

Once MCP is connected, call the `session_open` tool. If the Space contains more
than one project, pass the exact project name or id the human intends to use.
On success it returns a `session_id`, the project it actually opened, personal,
Space, and Project knowledge, and the working discipline.

Read the returned project name back to the human and confirm that project
knowledge contains either its `index.md` or the scoped fallback list. This is
the setup-complete point. Do not claim that future sessions automatically know
or select the correct project; each substantive session must call
`session_open` for the intended project.

**If you don't see this →**
- The tool isn't visible at all — MCP isn't connected yet (step 4). Recheck
  with `/mcp`.
- A permission error comes back — the consent screen may have been approved
  with a scope denied. Reconnect and approve fully on the consent screen.
- The wrong project opens — call `session_open` again in a new session with the
  intended project's exact name or id. Do not create a new project to recover
  from a typo.

### 6. Update

Since the plugin comes from a third-party marketplace, auto-update is off by
default. To manually pull the latest version:

```
/plugin marketplace update superself
```

To turn on auto-update, open `/plugin` in a session, go to the
**Marketplaces** tab, and enable auto-update for the `superself` marketplace.

**If you don't see this →**
- The update command fails — could be a network issue or the marketplace URL
  being temporarily unresponsive. Retry shortly.

## ChatGPT connector

Connector settings live outside the chat, so this part is a short walkthrough
you give your human — it takes a minute, once:

1. Open ChatGPT **Settings → Connectors**. (If there is no option to add a
   custom connector, enable developer/advanced mode under the Connectors
   settings first — naming varies by plan.)
2. Add a custom connector with the server URL `https://superselfs.com/mcp`.
3. A browser window opens the Superself authorization page — sign in with
   Google and approve the consent screen (it lists the access being granted).
4. Back in a chat, enable the superself connector for the conversation and
   ask the agent to call `session_open`. Verification criteria are in
   "Verify" inside the Claude Code section (step 5) — they are the same for
   every client.

## Claude web · Claude desktop connector

Same shape — the human adds the connector once, and every later session just
uses it:

1. Open claude.ai (or the desktop app) **Settings → Connectors → Add custom
   connector**.
2. Enter the server URL `https://superselfs.com/mcp` and connect.
3. Sign in with Google and approve the consent screen.
4. In a new chat, call `session_open` and verify as in step 5 of the Claude
   Code section.

## Codex

Codex supports authenticated streamable HTTP MCP servers. Run the steps below
in order.

### 1. Check whether Superself is already configured

```
codex mcp get superself
```

If it shows `https://superselfs.com/mcp`, keep the existing configuration and
continue to step 3. If it says the server does not exist, continue to step 2.
If the name exists but points at a different URL, tell the human before
replacing it; do not silently remove an unrelated configuration.

### 2. Add Superself and finish the same OAuth attempt

```
codex mcp add superself --url https://superselfs.com/mcp
```

Codex behavior varies by version. Some versions detect Superself's OAuth
support during `add` and open or print an authorization URL. When that happens,
the human signs in with Google and approves the consent screen. Keep that same
command running until it prints the final login result.

**Important for an Agent running the command:** a shell tool may yield while
the command is still waiting for browser approval and return a `session_id` or
similar process handle. That is not command completion. Poll that same process
until it exits and read its remaining output. If the browser says the
authorization succeeded, do not start a second OAuth flow just because the
first output chunk did not yet contain the success line.

Depending on the Codex version, a successful command ends with a message like
`Successfully logged in to MCP server 'superself'.`

If `add` exits successfully without opening or printing any authorization URL,
that Codex version expects a separate login command. Run it once:

```
codex mcp login superself
```

Also use it as recovery when a later authenticated tool call returns an
authentication error. Do not run it after `add` already opened an OAuth flow or
after a successful browser approval. It creates a new OAuth transaction with a
new state and localhost callback, which makes the human approve the same
connection twice.

### 3. Restart and verify the real tool

Restart Codex or open a new task so it reloads MCP configuration, then call
`session_open`. Setup is complete when it returns the intended project and its
Context. Treat that tool call as the definitive check; MCP list output varies
by Codex version and is not a substitute for an authenticated tool call.

**If you don't see this →**
- The add command is still waiting — return to its browser tab, finish approval,
  then poll the same command process again.
- The browser says success but the current task has no Superself tools — restart
  Codex or open a new task before changing OAuth configuration.
- The add command completed without ever showing an authorization URL — run
  `codex mcp login superself` once, finish that same flow, then restart.
- `session_open` returns an authentication error in a fresh task — run the
  recovery login command once, finish that same browser flow, restart, and retry.
- Codex is running through SSH or on a remote machine without a local browser —
  the standard flow is not supported; do not claim setup completion from config
  output alone.

## Other MCP clients

Any client that supports authenticated remote MCP works: add
`https://superselfs.com/mcp` as a remote MCP server in that client's MCP or
connector settings, complete the browser sign-in when prompted, then verify
with `session_open`. Exact menus vary by client and version — follow the
client's own documentation for adding a remote MCP server.

## Good to know

Answers to the questions humans (and careful agents) usually ask:

- **What does connecting grant?** Access to your own Superself account's
  knowledge (spaces, projects, sessions) through the MCP tools — the same
  data you see at superselfs.com. The consent screen lists the exact scopes.
- **Who does the sign-in?** Always the human, in a browser. Agents following
  this guide open the sign-in and hand it over.
- **Where does the token live?** In your client, locally, after approval.
  Removing the connector in the client ends its access.
- **Data handling**: retention and deletion are described at
  https://superselfs.com/privacy and https://superselfs.com/terms.
- **Source**: plugin repo https://github.com/spfn/plugin (marketplace pins a
  fixed version tag); operator Superfunction, contact `hello@fxy.global`.

### Still stuck?

If you're blocked on a step even after this, email `hello@fxy.global` with the
step number and the error message. Do not include OAuth tokens or other
credentials.