TGM Agent MCP

@tgm-research/agent-mcp is a stdio MCP server for safe TGM Survey Platform agent workspaces.

It lets MCP clients such as Claude Desktop connect to a TGM Agent Gateway workspace without exposing broad survey CRUD. The package runs locally, speaks MCP over stdio, and forwards allowed tool/resource calls to the TGM backend endpoint:

POST /api/agent-workspaces/mcp
Authorization: Bearer <agent-token>

The backend remains the security boundary. This package does not implement business logic and does not grant extra permissions.

Install

Use directly with npx:

npx -y @tgm-research/agent-mcp --help

Or install globally:

npm install -g @tgm-research/agent-mcp
tgm-agent-mcp --help

Configuration

Required:

• TGM_API_BASE_URL or --base-url: TGM API host, for example https://app.example.com or http://localhost:4088
• TGM_AGENT_TOKEN or --token: short-lived token issued by POST /api/agent-workspaces/:workspaceId/tokens

Optional:

• TGM_MCP_URL or --mcp-url: exact gateway MCP URL. Overrides TGM_API_BASE_URL.
• TGM_AGENT_WORKSPACE_ID or --workspace-id: helps resource autocomplete and client display.
• TGM_AGENT_TOKEN_FILE or --token-file: path to a file containing the token.
• TGM_MCP_TIMEOUT_MS or --timeout-ms: backend request timeout. Defaults to 30000.

Claude Desktop Example

{
  "mcpServers": {
    "tgm-agent": {
      "command": "npx",
      "args": ["-y", "@tgm-research/agent-mcp"],
      "env": {
        "TGM_API_BASE_URL": "https://app.example.com",
        "TGM_AGENT_TOKEN": "tgm_agent_...",
        "TGM_AGENT_WORKSPACE_ID": "workspace-uuid"
      }
    }
  }
}

Do not paste the agent token into a normal chat prompt. Put it in the MCP client environment/configuration.

Exposed Tools

The local MCP server exposes the same safe tools as the backend gateway:

• tgm_list_capabilities
• tgm_get_question_type_schema
• tgm_get_logic_schema
• tgm_get_script_schema
• tgm_get_snapshot
• tgm_preview_patch
• tgm_apply_patch_to_sandbox
• tgm_validate_sandbox
• tgm_create_preview_nonce
• tgm_run_test_session
• tgm_get_diff
• tgm_request_human_review

There are intentionally no tools for delete, publish, raw SQL, raw respondent results, billing, organization management, users, or normal survey CRUD.

Resources

The package exposes the workspace-scoped TGM resources supported by the backend:

• tgm://workspaces/{workspaceId}/snapshot
• tgm://workspaces/{workspaceId}/capabilities
• tgm://workspaces/{workspaceId}/diff
• tgm://workspaces/{workspaceId}/validation
• tgm://workspaces/{workspaceId}/test-runs

The backend validates that the bearer token can access only its own workspace.

Publish

Publishing requires npm access to the @tgm-research scope:

npm publish --workspace=@tgm-research/agent-mcp --access public