Self-Hosted Teamso MCP

Quick start

Requires Node.js 20 or later. Add this to your MCP client's configuration:

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

The version is pinned so npx does not run an old cached build.

Setup

The package runs over stdio and works with any MCP client that supports stdio.

Cursor

Open ~/.cursor/mcp.json with Cmd+Shift+P → Open MCP settings and add:

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

Claude Code

Add it, passing the token as an environment variable:

claude mcp add teamso --env TEAMSO_ACCESS_TOKEN=tms_pat_... -- npx -y @teamso/[email protected]

Claude Desktop

Add it to claude_desktop_config.json and restart Claude Desktop:

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

Windsurf

Add it under Windsurf → Settings → MCP:

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

Other clients

Any stdio client can run this command; the token is read from the TEAMSO_ACCESS_TOKEN environment variable:

TEAMSO_ACCESS_TOKEN=tms_pat_... npx -y @teamso/[email protected]

Authentication

The package uses a single credential: the personal access token you create on the MCP access page in Teamso. Put it in TEAMSO_ACCESS_TOKEN; the package sends it as the Authorization: Bearer header on every request.

TEAMSO_ACCESS_TOKEN=tms_pat_...

With the local package, requests come from your own IP address; if your company restricts IPs, that address must be allowed. Permissions, operations blocked for tokens and revocation work as on the hosted server.

Hosted MCP server · Authentication

Available tools

The package offers the same 34 tools as the hosted server. The table shows the Teamso REST endpoint each tool calls (relative to TEAMSO_API_BASE_URL); the help tools read the public guide bundle instead of the API.

Since 1.2.0 the package works across every module your permissions allow, through the generic API tools (find_api_endpoints, call_api_read, call_api_write...). The flow, the safety rules and examples are on the hosted server page.

Hosted MCP server · All modules

Prompts were added in version 1.1.0 of the package, and createMcpServer registers them together with the tools. In your own server use the registerPrompts and PROMPT_NAMES exports (@teamso/teamso-mcp/prompts).

Environment variables

The package reads these environment variables:

TEAMSO_TOOLSETS=core,leave,api

GitHub and npm

The source code is published on GitHub under the MIT licence and the package on npm.

• GitHub: Teamsocom/Teamso-MCP
• npm: @teamso/teamso-mcp

Using as a library

The package exports its core parts so you can build your own MCP server:

import { TeamsoClient } from "@teamso/teamso-mcp/client";
import { createMcpServer } from "@teamso/teamso-mcp/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const client = new TeamsoClient(process.env.TEAMSO_ACCESS_TOKEN!, "https://api.teamso.com/v1");
const server = createMcpServer(client, { name: "my-teamso-assistant" });

await server.connect(new StdioServerTransport());

Exports

You can also import the parts on their own:

import { TeamsoClient } from "@teamso/teamso-mcp/client";
import { registerTools, TOOL_NAMES } from "@teamso/teamso-mcp/tools";

registerTools(existingMcpServer, new TeamsoClient(token));
console.log(TOOL_NAMES); // ["search_help_articles", "get_help_article", ...]

A server that forwards other people's requests can sign the caller's IP so Teamso applies the company IP restriction and the audit log to the real caller. The secret must match the API's security.mcp-proxy.shared-secret (at least 32 characters):

const client = new TeamsoClient(userToken, "https://api.teamso.com/v1", {
  trustedProxy: { clientIp: request.ip, sharedSecret: process.env.TEAMSO_MCP_PROXY_SECRET! },
});

Self-hosting on your server

Build from source and run it on your own server (Node.js 20+):

git clone https://github.com/Teamsocom/Teamso-MCP.git
cd Teamso-MCP
npm ci
npm run build
export TEAMSO_ACCESS_TOKEN=tms_pat_...
node dist/index.js

Point your client at the build instead of npx:

{
  "mcpServers": {
    "teamso": {
      "command": "node",
      "args": [
        "/absolute/path/to/Teamso-MCP/dist/index.js"
      ],
      "env": {
        "TEAMSO_ACCESS_TOKEN": "tms_pat_..."
      }
    }
  }
}

The package builds itself on install (prepare), so a tagged release can also be installed straight from GitHub:

npm install github:Teamsocom/Teamso-MCP#v1.2.1