Teamso MCP Server

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools in other systems. Teamso's hosted MCP server at https://mcp.teamso.com/v1 serves clients that support Streamable HTTP and custom headers.

Claude Desktop needs OAuth for remote connections, so it uses the local npm package (@teamso/teamso-mcp). Every request runs with your personal access token and your permissions; the server stores nothing.

Links

• MCP specification
• GitHub repository
• npm package
• Create an access token
• Self-hosted MCP guide

Setup

Pick your client. They all use the same token: in Teamso, open MCP access at the very bottom of the left menu, create a token and put it in place of tms_pat_... in the examples.

Cursor

1. In Cursor, run Cmd+Shift+P → Open MCP settings.
2. Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "teamso": {
      "url": "https://mcp.teamso.com/v1",
      "headers": {
        "Authorization": "Bearer tms_pat_..."
      }
    }
  }
}

Restart Cursor; the Teamso tools appear in the MCP list.

Claude Code

One terminal command:

claude mcp add --transport http teamso https://mcp.teamso.com/v1 --header "Authorization: Bearer tms_pat_..."

To check, run claude mcp get teamso or type /mcp inside Claude Code.

claude mcp get teamso

Claude Desktop

Remote custom connectors in Claude Desktop need OAuth; Teamso uses tokens, so use the local package. Add it to claude_desktop_config.json and fully quit and reopen Claude Desktop:

{
  "mcpServers": {
    "teamso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@teamso/[email protected]"
      ],
      "env": {
        "TEAMSO_ACCESS_TOKEN": "tms_pat_..."
      }
    }
  }
}

Pin the version (@1.2.1): an unpinned npx keeps running an old cached build. Do not add the URL under Connectors.

Claude Desktop connection issues

• Configuration error: the entry needs type, command, args and env.
• Tools missing: install Node.js 20 or later, then fully quit Claude Desktop from the menu and reopen it.
• Calls fail at once: pin the package version; npx may be using an old cached build.
• Do not add a timeout field; the client may ignore it.

Windsurf

Windsurf → Settings → MCP (~/.codeium/windsurf/mcp_config.json). Windsurf expects the address in serverUrl:

{
  "mcpServers": {
    "teamso": {
      "serverUrl": "https://mcp.teamso.com/v1",
      "headers": {
        "Authorization": "Bearer tms_pat_..."
      }
    }
  }
}

Other clients

Any client with Streamable HTTP connects to https://mcp.teamso.com/v1 with the Authorization: Bearer tms_pat_... header. Clients that only speak stdio reach the hosted server through mcp-remote:

{
  "mcpServers": {
    "teamso": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.teamso.com/v1",
        "--header",
        "Authorization:Bearer ${TEAMSO_TOKEN}"
      ],
      "env": {
        "TEAMSO_TOKEN": "tms_pat_..."
      }
    }
  }
}

Clients that can only connect with OAuth are not supported.

Authentication

Teamso MCP uses a personal access token (tms_pat_...). Create it in Teamso on the MCP access page at the very bottom of the left menu; it is shown only once, when it is created.

Authorization: Bearer tms_pat_...

• The token acts as you, with your current permissions: what you cannot see on screen you cannot see through MCP either.
• Every request carries the Authorization: Bearer tms_pat_... header; the hosted server stores nothing and forwards the request to the Teamso API.
• Validity is 30 days, 90 days, 1 year or unlimited, and a user can have up to 10 active tokens; you can revoke a token on the same page at any time.
• Password, session and sign-in channel (phone, email) changes, token management, integration keys and SSI credentials, company security settings, support access, company deletion and webhook changes are not available with a token (403 ACCESS_DENIED).
• If your company restricts IP addresses, token requests follow that rule too; the hosted server forwards your real client IP in signed form.
• Writes made with a token are recorded in the audit log with MCP as the source.
• The token stops working if the user is deactivated or moves to another company.

Available tools

The hosted server and the npm package offer the same 34 tools. Every tool has typed input and output schemas and returns structuredContent plus a short text answer. Which tools you can use depends on your role and permissions.

On the hosted server the distributor account also sees the Landing CMS content prompts (seo_landing_page, translate_marketing_content); the hosted server gets them from the Teamso API.

All modules

The ready-made tools on this page cover the most common tasks. For everything else (expenses, requests, overtime, attendance, time tracking, shifts, recruiting, onboarding, inventory, document approval, surveys, reports, company settings...) the assistant uses the generic API tools. They read the Teamso API's endpoint catalog for you: only the endpoints your own permissions allow are listed and callable. If you cannot add leave, for example, the assistant cannot add leave through MCP either.

How it works

1. find_api_endpoints or list_api_modules finds the right endpoint.
2. describe_api_endpoint returns its parameters, body schema and whether it needs an SMS code.
3. Reads use call_api_read, which returns the data directly.
4. Changes use call_api_write: it shows a preview first and runs with confirm: true only after you agree.

A search returns endpoint ids (METHOD /path) and the effect of each endpoint:

{
  "name": "find_api_endpoints",
  "arguments": {
    "query": "masraf",
    "side_effect": "read"
  }
}

{
  "structuredContent": {
    "query": "masraf",
    "sideEffect": "read",
    "page": 1,
    "size": 20,
    "total": 2,
    "totalPages": 1,
    "endpoints": [
      {
        "id": "GET /expense-form/{id}",
        "module": "EXPENSE",
        "summary": "Masraf formu ayrıntısı",
        "sideEffect": "read",
        "smsCodeRequired": "never",
        "fileResponse": false
      },
      {
        "id": "GET /expense-form/listPagination",
        "module": "EXPENSE",
        "summary": "Masraf formları (sayfalı)",
        "sideEffect": "read",
        "smsCodeRequired": "never",
        "fileResponse": false
      }
    ]
  }
}

A read uses the id and the path values. The request carries the X-Teamso-Mcp-Intent: read header, and Teamso refuses (403) any request with that header that would change data.

{
  "name": "call_api_read",
  "arguments": {
    "id": "GET /expense-form/{id}",
    "path_params": {
      "id": "8f1c…"
    }
  }
}

The write tool returns a preview first: the exact request, the result of the schema check, delete and SMS warnings, and a one-line summary. Nothing reaches Teamso at this stage, and a request that does not match the schema is not sent even with confirm: true.

{
  "name": "call_api_write",
  "arguments": {
    "id": "POST /demand",
    "body": {
      "demandTypeId": "3b7e…",
      "message": "Yeni monitör talebi"
    }
  }
}

{
  "structuredContent": {
    "mode": "preview",
    "endpoint": {
      "id": "POST /demand",
      "module": "DEMAND",
      "sideEffect": "write",
      "smsCodeRequired": "never"
    },
    "request": {
      "method": "POST",
      "path": "/demand"
    },
    "summary": "Changes data: POST /demand — Create a request",
    "validation": {
      "checked": true,
      "valid": true,
      "errors": []
    },
    "nextAction": {
      "tool": "call_api_write",
      "arguments": {
        "id": "POST /demand",
        "body": {
          "demandTypeId": "3b7e…",
          "message": "Yeni monitör talebi"
        },
        "confirm": true
      },
      "reason": "Only after the user explicitly confirms this preview."
    }
  },
  "content": [
    {
      "type": "text",
      "text": "## Preview — nothing has been sent\n\n**Changes data: POST /demand — Create a request**\n…"
    }
  ]
}

Once you agree, the assistant repeats the call with confirm: true. For actions that need an SMS code it first calls request_sms_code, asks you for the code and adds it as otp_code:

{
  "name": "call_api_write",
  "arguments": {
    "id": "POST /expense-form/{expenseFormId}/finalize",
    "path_params": {
      "expenseFormId": "8f1c…"
    },
    "confirm": true,
    "otp_code": "123456"
  }
}

Illustrative response; fields vary by tool.

Safety rules

• Only endpoint ids from the catalog can be called; there are no free-form URLs. Login, token, password and security settings endpoints are listed for no one.
• Every request runs with the token owner's Teamso permissions, so the assistant cannot do anything you cannot do on screen. A request without permission is refused by the API with 403.
• Changes never run without a preview and an explicit confirmation; deletes get an extra warning in the preview.
• Actions that need an SMS code (e.g. finalizing an expense form) are confirmed with the code sent to your phone, as in the app.
• File responses come back embedded, up to 8 MB; uploads go in as base64, at most 10 files and 10 MB in total.
• Results over 40,000 characters are cut to the records that fit and marked truncated: true; nothing is cut silently.

Choosing tool groups

To give your assistant fewer tools, add ?toolsets= to the server address (or send the X-Teamso-Toolsets header). The local package takes the same selection from the TEAMSO_TOOLSETS environment variable. The default is every tool; an unknown group name is an error.

claude mcp add --transport http teamso https://mcp.teamso.com/v1?toolsets=core,leave,api --header "Authorization: Bearer tms_pat_..."

Groups: core, help, leave, approvals, employees, performance, communication, payroll, api

Request and response contract

Tools are called with MCP tools/call. Input is validated against JSON Schema 2020-12; a successful result has structuredContent (typed data for chaining) and content (a short summary for clients that only show text).

{
  "name": "calculate_leave_days",
  "arguments": {
    "leave_type_id": "6f1c…",
    "start": "2026-11-02",
    "end": "2026-11-04"
  }
}

When another tool has to follow, the result carries nextAction: the tool to call, its arguments and why. The leave flow is an example: calculate_leave_days → request_leave_otp → create_leave_request.

{
  "structuredContent": {
    "request": {
      "leaveTypeId": "6f1c…",
      "leaveTypeName": "Yıllık İzin",
      "start": "2026-11-02 09:00",
      "end": "2026-11-04 18:00",
      "workingDays": 3,
      "returnToWorkDate": "2026-11-05 09:00"
    },
    "remainingDays": 14,
    "remainingAfterRequest": 11,
    "canRequest": true,
    "problems": [],
    "nextAction": {
      "tool": "request_leave_otp",
      "arguments": {},
      "reason": "Creating the request needs an SMS code. After the user confirms these days, send the code, then call create_leave_request with the same leave_type_id, start, end and the otp_code."
    }
  },
  "content": [
    {
      "type": "text",
      "text": "## Yıllık İzin: 3 days\n\n- **Dates:** …\n- **Back at work:** 2026-11-05 09:00\n…"
    }
  ]
}

Illustrative response; fields vary by tool.

Errors come back with isError: true and a text that says what to do, ending with the Teamso API HTTP status and message_code (e.g. CREDIT_INSUFFICIENT, ITEM_NOT_FOUND).

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Your company does not have enough digital (SMS) credit for this step. Ask your Teamso administrator to top up credits.\n\n_Teamso API: HTTP 200 · `CREDIT_INSUFFICIENT`_"
    }
  ]
}

Dates: leave uses yyyy-MM-dd HH:mm Turkey time (a bare date starts at your shift start and ends at your shift end; 09:00 and 18:00 by default), goals and filters use yyyy-MM-dd, payroll terms yyyy-MM or yyyy.

get_payslip_pdf returns the payslip as an embedded application/pdf resource (base64).

Examples

Ask your assistant in plain language; it calls the tools in order.

How it works

1. The assistant sends the tool call with your token to https://mcp.teamso.com/v1.
2. The server forwards the request to the Teamso API on your behalf; your permissions and company rules (IP restrictions, approval chains, SMS confirmation) apply as usual.
3. The answer returns to the assistant as typed data and short text. The server is stateless: no session or token is stored.
4. New permissions and rules in Teamso apply to the tools straight away; nothing needs reinstalling.

Tool reference

The parameters of every tool. Optional ones can be left out.

Troubleshooting

401 Unauthorized

The token is wrong, expired or revoked. Create a new one on the MCP access page; the header must read Bearer tms_pat_....

403 ACCESS_DENIED

You lack the permission, or the operation is not available with a token (password, security settings, token and integration key management).

403 IP_NOT_ALLOWED

Your company's IP restriction rejected the request. With the local package, your machine's IP address must be allowed.

CREDIT_INSUFFICIENT

Creating and cancelling leave uses SMS and digital credit; ask your company admin to top up credits.

OTP_NOT_DONE

The SMS code was not verified or its 3 minutes ran out. Ask for a new code with request_leave_otp.

429 Too Many Requests

The hosted server limits requests per token per minute; wait for the Retry-After seconds given in the response, then retry.

Endpoint not found

If find_api_endpoints cannot find an action, or describe_api_endpoint says "not found", the token owner lacks the permission for it or the endpoint is closed to MCP (login, tokens, passwords). Ask your company administrator for the permission; a new permission applies right away.

Tools do not show up

Fully restart the client; with the local package make sure you run Node.js 20+ and a pinned version.

FAQ