Skip to main content

Connecting Claude Desktop to Teamso

Explains how to add the Teamso MCP package to Claude Desktop with the claude_desktop_config.json file, how to restart the app and how to test the connection.

This article explains how to connect the Claude Desktop app to your Teamso account. The person who will use the assistant does this on their own computer.

Claude Desktop asks for OAuth when it connects to a remote server as a Custom Connector, while Teamso uses a personal access token. So in Claude Desktop, Teamso connects through the open-source Teamso MCP package (@teamso/teamso-mcp) that runs on your computer. npx downloads the package automatically and it talks to Teamso directly; you do not need to install anything else.

Before you start

  • You need an MCP access token (Creating an access token).

  • Node.js 20 or later must be installed on your computer (the npx command comes with Node.js). Type node -v in a terminal to see the version.

  • A current version of Claude Desktop must be installed.

  • If your company restricts IP addresses, your computer's IP address must be allowed (Security and access settings).

Step by step

  1. In Teamso, create a new token on the MCP access screen. In the Connect your assistant card, Claude Desktop is selected (Recommended). Copy the setup with Copy at the top right of its block. Your token (Token added) and the pinned package version are already in it; the card also shows the package name and the Node.js 20+ requirement.

    Claude Desktop setup in the Connect your assistant card

    If you created the token earlier, copy the same setup with the placeholder and replace the highlighted tms_pat_... with your token. If you lost your token, use the create a new token link in the note below the block; the setup fills in automatically.

  2. In Claude Desktop, open Settings > Developer and click Edit Config to open the claude_desktop_config.json file. The file is at:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  3. Paste the setting into the file. If the file already lists other servers, add only the "teamso": { ... } part inside the existing "mcpServers". The setting looks like this:

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

  4. Save the file.

  5. Fully quit Claude Desktop and open it again. Closing the window is not enough: on macOS use Quit in the menu (or Cmd+Q), on Windows use Quit on the Claude icon in the system tray.

  6. In a new chat, check that the teamso server and its tools appear in the tools menu.

  7. Test the connection by asking "How many leave days do I have left in Teamso?". Claude may ask for permission at the first tool call; allow it.

Result

Claude Desktop uses the Teamso tools with your permissions. Because the package connects to Teamso directly from your computer, your company's IP restriction applies to your computer's IP address. When you revoke the token or it expires, the connection stops at once; put the new token in TEAMSO_ACCESS_TOKEN in the same file and restart Claude Desktop.

Note: do not add the Teamso address (https://mcp.teamso.com/v1) under Connectors in Claude Desktop; that list needs OAuth and does not work with a token.

The local package has the HR tools only. The distributor account's Landing CMS tools are only served from the server address; the screen says so in a note while Claude Desktop is selected. To use those tools in Claude Desktop, pick the Other (mcp-remote) setup in the card.

Common problems

Symptom: Claude Desktop shows a configuration error on start.
​Cause: The JSON is broken, or the teamso entry lacks one of type, command, args and env.
​Solution: Copy the setting again from the MCP access screen and check the commas and braces. Do not add a timeout field; the client may ignore it.

Symptom: The Teamso tools do not show up.
​Cause: Node.js is not installed or is older than 20, or Claude Desktop was not fully quit.
​Solution: Install Node.js 20 or later, then fully quit Claude Desktop from the menu and reopen it.

Symptom: Tool calls fail at once.
​Cause: Without a pinned version, npx may keep running an old cached build of the package.
​Solution: Write the package name with its version in args (as in the ready-made setting on screen) and restart Claude Desktop.

Symptom: A "401" or "IP_NOT_ALLOWED" error.
​Cause: The token is wrong, expired or revoked, or your IP address is not allowed.
​Solution: See Troubleshooting.

Related articles

Did this answer your question?

Related Articles