# Install and connect

## Choose the environment

| Environment                | Streamable HTTP server URL              | Suggested connection name |
| -------------------------- | --------------------------------------- | ------------------------- |
| Production (default)       | `https://www.skatteguru.se/api/v2/mcp`  | `skatteguru`              |
| Beta (only when requested) | `https://rizz.skatteguru.se/api/v2/mcp` | `skatteguru_beta`         |

Use the public web endpoint above, including `/api/v2/mcp`. The downstream
`rust-beta.skatteguru.se/api/actions/mcp` is not the public setup URL.
Use browser OAuth with PKCE. No static bearer-token variable, custom
Authorization header, client secret or paid pass is needed just to configure
the connection. Export access is checked separately for the income year.

The normal workflow scopes are:
`documents:read documents:upload tax:read tax:export`.
They allow document reads/uploads and tax reads/exports. A read-only user can
request just `documents:read tax:read`, with upload/export tools unavailable.
Do not request legacy `mcp:read` or broader account/delete/write permissions for
this workflow.

## Install the skill files

Install the complete `skatteguru/` folder, including its three reference files.
Do not install only `SKILL.md`, which would leave broken references.

- **Codex:** use the host's skill installer if available; otherwise place the
  folder at `~/.agents/skills/skatteguru/` (personal) or
  `.agents/skills/skatteguru/` (project). Older installations may use
  `~/.codex/skills/`; follow the host's documented location. Reuse an existing
  skill or show the differences before replacing local edits.
- **Claude Code:** place it at `~/.claude/skills/skatteguru/` (personal) or
  `.claude/skills/skatteguru/` (project).
- **Claude web/desktop:** upload the published `skatteguru.zip` through
  Customize > Skills > Create skill > Upload a skill, then enable it. Connect
  the remote MCP separately through the host's connector settings. Organization
  policy can limit both features.
- **Other chatbots:** use their supported skill/import mechanism. Reading these
  instructions in one chat is not proof that a persistent skill was installed.
  If local files or settings are inaccessible, give the user the ZIP and manual
  steps instead of claiming to have changed them.

The published bundle is at `https://www.skatteguru.se/skills/skatteguru.zip`.
For a beta release, use the same path on `https://rizz.skatteguru.se`.
Review only the skill files; installing this instructions-only bundle needs no
shell installer, package dependency, cloned application repository or secrets.

## Codex

First inspect existing servers with `codex mcp list`. Reuse a matching URL;
do not overwrite a same-named server pointing elsewhere.

```sh
codex mcp add skatteguru --url https://www.skatteguru.se/api/v2/mcp
codex mcp login skatteguru
```

For beta, use `skatteguru_beta` and the beta URL in both setup and verification.
If registration returns `invalid_scope` and mentions separate MCP/Actions
sessions, retry login with explicit resource scopes:

```sh
codex mcp login skatteguru --scopes documents:read,documents:upload,tax:read,tax:export
```

This is a compatibility fallback for older discovery responses; normally scopes
are discovered. In Codex's custom MCP settings, choose **Streamable HTTP**, enter
the URL, and leave the bearer-token and header fields empty. Saving the server
and authenticating are separate steps. Use the host's Authenticate action or
the CLI login command; `/mcp` is a command inside the terminal UI, not a shell
command. Refresh the tool catalog or start a new chat if tools do not appear.

## Claude Code

Check `claude mcp list` for an existing connection. For a new personal connection:

```sh
claude mcp add --transport http --scope user skatteguru https://www.skatteguru.se/api/v2/mcp
```

Run `/mcp` inside Claude Code, select the server and authenticate in the browser.
Use the beta name and URL only if beta was requested. An existing remote app
connector and a locally configured MCP server can have separate OAuth grants;
authenticating one does not repair the other.

## Verify and troubleshoot

1. After browser sign-in and consent, discover the available tools.
2. Call `ping`, then `search_documents` with `limit: 1`. Empty results can be
   valid; an OAuth error is not an empty account. Show only minimal metadata so
   the user can recognize whether they signed into the intended account.
3. Report the actual calls and results. Do not say upload or export was verified
   based on these read checks alone.

If no browser opens, capture the client error first; registration can fail
before sign-in. For 401, reauthenticate the same connection. For 403, check the
requested scopes and access requirement. For 429, respect retry guidance and
reduce polling. For internal errors, report the tool, environment and time;
never include tokens, passwords or signed upload URLs in a support message.
Do not repeatedly create registrations, disable authentication, or replace the
connection with a different environment to mask a failure.

Authoritative host instructions:
[Codex MCP](https://developers.openai.com/codex/extend/mcp),
[Codex skills](https://developers.openai.com/codex/skills),
[Claude Code MCP](https://code.claude.com/docs/en/mcp),
[Claude Code skills](https://code.claude.com/docs/en/skills),
[Claude skill upload](https://support.claude.com/en/articles/12512180-use-skills-in-claude).