MCP server
Connect your AI assistant to Selfcare
Selfcare has an MCP (Model Context Protocol) server for AI assistants. Each person signs in with their own Selfcare account. The assistant can then check leave balances, request absences, log expenses, trips and mileage, open documents and handle approvals, always with the permissions that person has in the app.
https://api.selfcare.work/mcpFor AI assistants: this page also exists in Markdown.
Summary
- Server URL
https://api.selfcare.work/mcp- Transport
- Stateless Streamable HTTP: each request is a POST with JSON-RPC.
- Authentication
- OAuth 2.1 with PKCE (S256), using the person's own account. There is no shared fixed token.
- Authorisation server
https://api.selfcare.work- Client registration
- Dynamic (RFC 7591): the client registers itself, with no keys to copy.
- Price
- Included in every plan, at no extra cost.
How to connect
The path is the same in every client: you add the URL, sign in with your Selfcare account, choose the company and approve what the assistant can do. There is no token to copy.
Claude
- In Settings → Connectors, choose Add custom connector.
- Give it a name (Selfcare) and paste the URL https://api.selfcare.work/mcp.
- Click Connect. The Selfcare authorisation screen opens: sign in with your account, choose the company and confirm what the assistant can do.
Claude Code
- In the terminal, add the server with the command below.
- Inside Claude Code, run /mcp and choose the selfcare server. The browser opens so you can sign in to Selfcare and authorise.
claude mcp add --transport http selfcare https://api.selfcare.work/mcpChatGPT
- In Settings → Apps and connectors, turn on developer mode (in the advanced settings) and choose Create.
- Paste the URL https://api.selfcare.work/mcp and choose OAuth as the authentication.
- Confirm on the Selfcare authorisation screen, as with Claude.
Cursor
- Open the Cursor settings, MCP section, and add the server to mcp.json (project or global).
- On first use, Cursor opens the browser so you can sign in to Selfcare and authorise.
{
"mcpServers": {
"selfcare": { "url": "https://api.selfcare.work/mcp" }
}
}Other MCP clients
Any client that speaks MCP over Streamable HTTP and does OAuth 2.1 with discovery connects the same way:
- Configure a remote MCP server with the URL https://api.selfcare.work/mcp.
- The client receives the 401, reads the metadata, registers itself and opens the browser on the Selfcare authorisation screen.
- You sign in with your account, choose the company and approve the scopes. The screen warns that this is an AI assistant.
Without OAuth: API key
A client that doesn't do OAuth can use a personal API key, created in Settings → API with the scopes of the tools you'll use. The key is yours: keep it out of repositories and shared files.
- Send the key in the Authorization header, as in the example.
{
"mcpServers": {
"selfcare": {
"url": "https://api.selfcare.work/mcp",
"headers": { "Authorization": "Bearer <your API key>" }
}
}
}Discovery and authorisation
For anyone writing a client: the server follows the MCP authorisation specification. Everything is discovered from the server URL.
- Without a token, a request to https://api.selfcare.work/mcp returns 401 with the WWW-Authenticate header, which points to the protected resource metadata.
- Protected resource metadata (RFC 9728): https://api.selfcare.work/.well-known/oauth-protected-resource/mcp. It also answers at the root, https://api.selfcare.work/.well-known/oauth-protected-resource, for clients that look there.
- Authorisation server metadata (RFC 8414): https://api.selfcare.work/.well-known/oauth-authorization-server. It lists the authorisation, token, revocation and registration endpoints.
- Dynamic client registration (RFC 7591): https://api.selfcare.work/oauth/register. Public clients only, with PKCE S256 required.
- The token is issued for the resource https://api.selfcare.work/mcp (RFC 8707) and sent in the Authorization: Bearer header. An MCP token doesn't work on the REST API, or the other way round.
HTTP/2 401
WWW-Authenticate: Bearer realm="selfcare", resource_metadata="https://api.selfcare.work/.well-known/oauth-protected-resource/mcp"Scopes
The client asks for these scopes and you approve them on the authorisation screen. Even with a scope, the assistant only does what your profile allows.
| Scope | What for |
|---|---|
| me:read | Who I am, the company, the role and the day's summary. |
| absences:read | Visible absences, leave balance, who is out and the approvals inbox. |
| absences:write | Request and cancel absences. |
| absences:decide | Approve and reject absences. |
| expenses:read | Visible expenses and categories. |
| expenses:write | Create expenses, upload receipts and send for approval. |
| expenses:decide | Approve and reject expenses. |
| trips:read | Visible business trips and ajudas de custo (per diem). |
| trips:write | Log and cancel business trips. |
| trips:decide | Approve and reject business trips. |
| mileage:read | Visible mapas de kms (mileage logs) and the person's vehicles. |
| mileage:write | Create logs, add routes, calculate distances, submit and cancel. |
| mileage:decide | Approve and reject mileage logs. |
| documents:read | Documents allowed through MCP and temporary links to open them. |
| employees:read | Employee directory and shared birthdays. |
The payments:write scope (mark as paid or revert a payment) is sensitive. It sits outside the scopes a self-registered MCP client can request. The payment tools only work with an app registered in Settings → API that declares this scope, and with the explicit consent of an owner or HR.
Tools by area
The tools the assistant sees once connected, by area. Each one calls the Selfcare API with your token and the app's rules.
Me and summary
get_meme:read
User, company, role, employee profile, teams they lead and the connection's scopes.get_my_summaryme:read
Leave balance, upcoming absences, pending decisions, unread documents and notifications, in a single call.
Absences
get_vacation_balanceabsences:read
Leave balance.list_absence_typesabsences:read
The company's absence types.list_absencesabsences:read
Visible absences.get_absenceabsences:read
One absence, without attachments such as medical certificates.request_absenceabsences:write
Request leave or another absence.cancel_absenceabsences:write
Cancel a request, or ask to cancel approved leave.who_is_outabsences:read
Who is out on a given day, with names and dates only.list_pending_approvalsabsences:read
Requests waiting for the user's decision (absences, expenses and trips).approve_absenceabsences:decide
Approve an absence the user can decide.reject_absenceabsences:decide
Reject an absence the user can decide.
Expenses
list_expensesexpenses:read
Visible expenses, with status and reimbursement date.get_expenseexpenses:read
One expense, with receipts and reimbursement status.list_expense_categoriesexpenses:read
Expense categories.create_expenseexpenses:write
Create a draft expense.get_expense_receipt_upload_urlexpenses:write
Get a link to upload the receipt.add_expense_receiptexpenses:write
Confirm the uploaded receipt, with the amount.submit_expenseexpenses:write
Send the expense for approval.approve_expenseexpenses:decide
Approve an expense.reject_expenseexpenses:decide
Reject an expense, with a note for the person.
Ajudas de custo (per diem and business trips)
list_business_tripstrips:read
Visible business trips, with the per diem.get_business_triptrips:read
One trip, with status, decision and amounts.create_business_triptrips:write
Log a trip, which goes straight to approval.cancel_business_triptrips:write
Cancel a trip.approve_business_triptrips:decide
Approve a trip.reject_business_triptrips:decide
Reject a trip, with a note for the person.pay_business_trippayments:write
Mark as paid (only with payments:write).revert_business_trip_paymentpayments:write
Revert the payment (only with payments:write).
Mileage logs
list_mileage_mapsmileage:read
Visible mileage logs.get_mileage_mapmileage:read
One log, with each route and the totals.create_mileage_mapmileage:write
Open the log for a month.add_mileage_linemileage:write
Add a route to the log.submit_mileage_mapmileage:write
Send the log for approval.cancel_mileage_mapmileage:write
Cancel the log.approve_mileage_mapmileage:decide
Approve a log.reject_mileage_mapmileage:decide
Reject a log, with a note for the person.pay_mileage_mappayments:write
Mark as paid (only with payments:write).revert_mileage_map_paymentpayments:write
Revert the payment (only with payments:write).list_my_vehiclesmileage:read
The user's vehicles, with the default one.calculate_distancemileage:write
Calculate the km of a route, if the company has the maps service turned on.
Documents
list_documentsdocuments:read
Documents allowed through MCP.get_document_linkdocuments:read
Temporary link (5 minutes) to open a document. The access is logged.
Employees and teams
search_employeesemployees:read
Search the directory as the user sees it in the app, with each person's teams and who leads them.list_teamsemployees:read
The company's teams, with who leads each one and how many people it has (the leader counts once).birthdaysemployees:read
A month's birthdays, only of people who share them (day and month).
Prompts
request_vacation
Book leave after checking the balance.
Limits and rules
MCP is one more door into the same app, not a shortcut around its rules.
The person's profile decides
The assistant acts as the person who authorised the connection, in the company they chose. It sees and does only what that person sees and does in the app, with the same roles and permissions.
Approvals are respected
Each tool uses the Selfcare API, with the app's rules: who sees, who decides, each module's Who approves setting and idempotency. An assistant never gives anyone a decision power that person doesn't have in the app.
No salaries or IBANs
Payroll, contracts, pay and the full IBAN never leave through MCP. Anything shaped like an IBAN is masked before it goes out.
Documents from the allowed list only
Through MCP you can see only the company's internal rules, policies and manuals, and the person's own expense receipts. Payslips, contracts, identity documents, health documents, medical certificates and disciplinary documents never leave.
No accountants
Accounts with the accountant role can't use MCP: the authorisation screen refuses and the server responds 403.
Everything is logged
Each write goes into the company's audit log, marked as coming from MCP. The person revokes access in Settings → API → Authorized apps.
- Full technical documentation at api.selfcare.work/docs
- The REST API and webhooks in API and integrations
Frequently asked questions
Do I need a key or a token to connect the assistant?+
No. The MCP client registers itself and opens the Selfcare authorisation screen, where you sign in with your account. The API key is only for clients that don't do OAuth.
Does the assistant see the whole company's data?+
It sees the same as you see in the app, and nothing more: your role and permissions apply to the assistant too.
Can the assistant see salaries?+
No. Payroll, contracts, pay and the full IBAN never leave through MCP.
How do I disconnect the assistant?+
In Settings → API → Authorized apps, revoke the assistant's connection.
Does it cost anything?+
No. The MCP server is included in every plan, as are the API and webhooks.
Not using Selfcare yet?
See how it works in a demo: leave, expenses, documents and salaries, also from your AI assistant.