> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seosorted.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting a client

> Sign in once in your browser and your AI agent is connected. No keys to copy.

The server lives at one URL:

```
https://seosorted.ai/api/mcp
```

Paste it into your MCP client. The client discovers everything else, opens your browser, and
you approve the connection by signing in the way you always do. **There is no key to create,
copy or store.**

## What happens

<Steps>
  <Step title="Your client discovers the server">
    It fetches `/.well-known/oauth-protected-resource`, finds the authorization server, and
    registers itself automatically. Nothing for you to configure.
  </Step>

  <Step title="Your browser opens">
    You land on seosorted.ai. If you are already signed in, you skip straight to the next
    step — it is the same session as the dashboard.
  </Step>

  <Step title="You choose what it gets">
    Pick the workspace it may work in, and tick what it may do. Then **Connect**.
  </Step>

  <Step title="Done">
    The client receives its own credential and the browser closes. Ask the agent to call
    `get_site_profile` to confirm.
  </Step>
</Steps>

## The approval screen

You are granting access to **one workspace**, not your whole account:

|                                |                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Workspace**                  | Which site the agent works on. It can never see another one. If you only have one workspace, this is skipped. |
| **Read your SEO data**         | Keywords, articles, audits, site profile.                                                                     |
| **Research and write content** | Keyword lookups, audits, article generation. Spends your monthly credits.                                     |
| **Publish to your website**    | Send articles to your CMS. **Off by default** — tick it deliberately.                                         |

Anything you leave unticked is refused at the moment it is used, not just hidden. An agent
without the publish permission cannot publish, whatever it tries.

Access also never exceeds your own. The agent acts as you, and your role in that workspace is
re-checked on every single call — if you are demoted or removed, its access changes with you.

## Setting it up

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http --scope user seosorted https://seosorted.ai/api/mcp
    ```

    Your browser opens for approval on first use.

    `--scope user` makes it available in every project. Leave it off and the connection is
    only added to the directory you ran the command in.
  </Tab>

  <Tab title="Other MCP clients">
    Add a remote MCP server with:

    * **Transport:** HTTP (Streamable HTTP)
    * **URL:** `https://seosorted.ai/api/mcp`

    Any client supporting the MCP authorization spec handles discovery, registration and the
    browser flow for you.
  </Tab>

  <Tab title="API key (headless)">
    For CI, cron or a script with no browser, a workspace **Admin** can mint a long-lived key:

    ```bash theme={null}
    curl -X POST https://seosorted.ai/api/v1/workspaces/YOUR_WORKSPACE_ID/api-keys \
      -H 'Content-Type: application/json' \
      -b '__session=YOUR_SESSION_COOKIE' \
      -d '{ "name": "CI", "scopes": ["read", "content"] }'
    ```

    The key is returned once and only its hash is stored. Send it as
    `Authorization: Bearer sk_ss_live_…`.

    <Warning>
      Prefer signing in. A key is a standing credential with no browser approval behind it — if
      it leaks, anyone can spend your credits and, with the `publish` scope, write to your site.
      Never commit one.
    </Warning>
  </Tab>
</Tabs>

## Checking it worked

Ask the agent to call `get_site_profile`:

```
outrank.so — https://outrank.so
Plan FREE · billing state free
- Articles: 0/3
- Audits: 1/1
- Keyword lookups: 0/100

This connection has scopes: read, content.
```

The last line is what you approved. If the workspace is wrong, reconnect and pick a different
one on the approval screen.

## Disconnecting

Remove the server in your MCP client, or revoke it from SeoSorted — either stops it. Access
tokens last an hour and refresh silently until revoked.

## When a connection stops working

<AccordionGroup>
  <Accordion title="It asks you to sign in again">
    Normal. Access tokens expire hourly and the client refreshes them for you. You only see
    the browser again if the connection was revoked or unused for 30 days.
  </Accordion>

  <Accordion title="You are no longer a member of this workspace">
    The connection acts as you. Losing membership ends it — there is no lingering access.
  </Accordion>

  <Accordion title="This workspace's subscription has lapsed">
    Payment failed and the grace period ran out. Resubscribe and it reconnects.
  </Accordion>

  <Accordion title="This connection was not granted the … scope">
    You left that permission unticked. Reconnect and approve it.
  </Accordion>

  <Accordion title="Too many MCP calls">
    120 calls per minute. Ask the agent to batch its work.
  </Accordion>
</AccordionGroup>