# MCP authentication

Every Salaxy MCP server needs a sign-in: the **demo** servers (`demo-payroll.salaxy.com`, `demo-reporting.salaxy.com`) with a free demo account, the **production** servers (`payroll.salaxy.com`, `reporting.salaxy.com`) with your own Salaxy account. The addresses are on [Connect a client](https://code.salaxy.com/get-started/agentic/index.md).

## One credential per job

Each way of working with Salaxy has its own credential. **Do not reuse one for another job.**

| Job | Credential | Where |
|---|---|---|
| Your server calls the REST API | Access token from `POST /oauth2/token` — password flow while developing, a signed JWT in production | [REST authentication](https://code.salaxy.com/security/rest-authentication.md) |
| Your page shows Salaxy's payroll UI | A user access token, in the iframe URL hash on the first load | [Embedded white label](https://code.salaxy.com/white-label/how-it-works.md) |
| An AI client works in the user's payroll | **Browser sign-in** — the user approves access; nobody handles a token by hand | This page |

## A user connects their own AI client

Claude, ChatGPT, Claude Code, Codex and other clients connect with the [MCP authorisation](https://modelcontextprotocol.io/specification) flow: the client discovers Salaxy's sign-in from the server, opens a browser window, and the user signs in and approves access. Salaxy's sign-in server accepts clients that publish their own identity (Client ID Metadata Documents); it does not offer dynamic client registration.

1. **Add the server** in the client, named after its agent and environment — `salaxy-payroll-demo`, `salaxy-payroll`. The steps per client are on [Connect a client](https://code.salaxy.com/get-started/agentic/index.md); production differs from the demo only by its address.
2. **Sign in** on the Salaxy page the client opens. Only an existing **company** account can sign in; the sign-in does not create accounts.
3. **Approve** access and return to the client.

**Keep sign-in in the browser:**
Never paste a password, one-time code, access token or authorisation code into an AI chat. If the client does not open a browser, open the sign-in address it shows yourself. An agent that asks for a token is doing it wrong — stop, and use the browser flow.

## Choosing the employer

With today's Salaxy sign-in, the agent works in **the company account the user signed in to** — not in other companies, such as an accounting firm's customers. Choosing between several employers comes with Salaxy's new authentication server.

- `employer_list` returns the employers the user may act for — today only the signed-in account, marked as the default (`isSelf`).
- When there is a choice and no default, **the user chooses — the agent never chooses for them** — and the agent calls `employer_select`. The choice holds from then on, also in later conversations. This needs the new authentication server.
- Every other tool takes an optional `employerId`; left empty, it works in the default employer.
- **An agent never has more rights than the signed-in user.** What each user level may do is published with the server — see [Permissions and human approval](https://code.salaxy.com/security/permissions.md).

## A partner's embedded agent

When the agent runs inside a partner's product, the user has already signed in to that product. There is no browser pop-up: **the partner's backend gets an MCP access token for that user** from Salaxy's token endpoint (`token_endpoint` in the metadata at `/.well-known/oauth-authorization-server` on the API host), in one of two ways:

- **A signed JWT assertion**, made with the same certificate as in the [impersonation flow for single sign-on](https://code.salaxy.com/security/impersonation.md). For MCP it must also have a unique `jti` and a lifetime of at most 10 minutes, and `salaxy_proxy_act` is not supported.
- **The user's Salaxy access token**, exchanged by an agent host that Salaxy has registered.

Either way, only company accounts are accepted, and the MCP access token lasts at most one hour — get a new one when it expires. The remaining details are published with the MCP server.

## One sign-in per country

Each country's MCP servers have **their own sign-in** for now. Finland's comes first; [Sweden](https://code.salaxy.com/countries/sweden.md) will have its own endpoint and sign-in. Name servers by country so the agent picks the right one by the employer's country.

## Check that it worked

Ask the client:

> Use Salaxy. Which employers can I act for?

You are connected when the agent calls `employer_list` and names employers from the account you approved. If it asks you to paste a token, stop and use the browser flow.

## Remove access

- Remove or disconnect the server in the client — `claude mcp remove salaxy-payroll-demo`, or delete the connector in Claude or ChatGPT.
- **Removing it from the client does not by itself revoke the access you approved.** How to revoke an approval on the Salaxy side is published with the server.

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| The client says authentication is required | Sign in again: run the client's login step, or choose Connect |
| The browser did not open | Open the address the client shows |
| The wrong employer | Sign in again with the right company account. With the new authentication server: ask the agent to list employers and choose again — `employer_select` |
| The connector cannot be added at all | The client's plan or a workspace administrator has disabled custom MCP servers — a client setting, not a Salaxy problem |
| A tool you expected is missing | It belongs to another agent — salary slips and reports are on the Report Agent, not the Payroll Agent — or to an agent that is coming soon |

## From demo to live

| | Demo | Production |
|---|---|---|
| Servers | `demo-payroll.salaxy.com`, `demo-reporting.salaxy.com` | `payroll.salaxy.com`, `reporting.salaxy.com` |
| Sign-in | Browser sign-in, free demo account | Browser sign-in, your Salaxy account |
| Data | Sample data only | Your employers' real payroll data |
| Tools | The same as in production — see the [MCP reference](https://code.salaxy.com/reference/mcp.md) | Calculations, payrolls, employments, absences, holidays, invoices; reports on the Report Agent |
| Paying salaries | Not possible | Preview → **a person approves** → confirm |

The tools and the skills are the same in both: moving to production changes the address and the account, nothing else.
