MCP Setup

MCP Setup Guide

TeamLoop uses the Model Context Protocol (MCP) to connect with AI assistants like Claude. This guide covers setup for both SaaS and AWS Marketplace deployments.

How Authentication Works

TeamLoop uses OAuth 2.0 Device Authorization for all MCP connections. There are no API keys — you sign in with your browser on first use, and the token is stored locally and refreshed automatically.

1. You configure your MCP client with the TeamLoop MCP server
2. On first use, a browser window opens for sign-in
3. After authenticating, the token is stored locally
4. Subsequent sessions reuse the stored token — no repeated sign-in

Deployment	Identity Provider
SaaS	Auth0 (app.teamloop.io)
Marketplace	AWS Cognito (your deployment)

SaaS Setup

Claude Desktop

Locate your config file:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/claude/claude_desktop_config.json

Add TeamLoop to your mcpServers configuration:

{
  "mcpServers": {
    "teamloop": {
      "command": "npx",
      "args": ["-y", "@teamloop/mcp-server"]
    }
  }
}

Restart Claude Desktop. On first tool use, a browser window opens for sign-in.

Claude Code (CLI)

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "teamloop": {
      "command": "npx",
      "args": ["-y", "@teamloop/mcp-server"]
    }
  }
}

Then trigger authentication:

claude /mcp

Cursor

Go to Settings > MCP and add a new server with the same command and args as above.

Other MCP Clients

The server runs via stdio using the npx @teamloop/mcp-server command. Any MCP client that supports stdio transport can use it.

Setting	Value
Command	npx
Args	-y, @teamloop/mcp-server
Transport	stdio
Authentication	OAuth 2.0 Device Flow (automatic)

Environment Variables

Variable	Required	Description
TEAMLOOP_API_URL	No	Custom API URL (default: https://api.teamloop.io)
TEAMLOOP_LOG_LEVEL	No	Logging level (debug, info, warn, error)

Direct Invocation

You can run the MCP server directly:

npx @teamloop/mcp-server

The server communicates via stdin/stdout using newline-delimited JSON-RPC.

AWS Marketplace Setup

Marketplace deployments use OAuth 2.0 with Cognito. Users sign in through the Cognito hosted UI — the same credentials they use for the dashboard. If SAML federation is enabled, corporate SSO works automatically.

Find Your MCP Endpoint

Your MCP endpoint URL comes from the CloudFormation stack outputs:

• With custom domain: https://YOUR_DOMAIN/mcp/
• Without custom domain: https://ALB_DNS_NAME/mcp/ (from the ALBURL output)

Cursor

Go to Settings > MCP and add a new server:

{
  "mcpServers": {
    "teamloop": {
      "url": "https://YOUR_DOMAIN/mcp/"
    }
  }
}

Restart Cursor. On first MCP tool use, a browser window opens for Cognito sign-in.

Claude Code (CLI)

claude mcp add teamloop --transport http https://YOUR_DOMAIN/mcp/

Then trigger authentication:

claude /mcp

A browser window opens for Cognito sign-in. After authenticating, the token is stored and Claude Code can use TeamLoop tools.

VS Code (Claude Code Extension)

Add to your settings.json:

{
  "claude-code.mcpServers": {
    "teamloop": {
      "url": "https://YOUR_DOMAIN/mcp/"
    }
  }
}

Other MCP Clients

For any MCP-compatible client that supports HTTP transport:

Setting	Value
Server URL	https://YOUR_DOMAIN/mcp/
Transport	HTTP (Streamable)
Authentication	OAuth 2.0 / Bearer Token

Replace YOUR_DOMAIN with your custom domain or the ALB DNS name from the stack outputs.

Verifying Setup

After configuration, verify TeamLoop is working:

1. Start a new conversation in your AI assistant
2. Ask: “What TeamLoop tools are available?”
3. The assistant should list the TeamLoop tools (e.g., teamloop_query, teamloop_save_knowledge)

If the tools don’t appear:

• Check the config file syntax
• Run npx @teamloop/mcp-server directly to check for errors
• Enable debug logging (see below)

Security

TeamLoop respects your integration tokens:

• Only accesses tools you’ve connected
• Only sees data your API tokens have access to
• Integration tokens are encrypted at rest using pgcrypto

Troubleshooting

”Server not found” Error

• Ensure Node.js 18+ is installed
• Try running npx @teamloop/mcp-server manually
• Check network connectivity

Authentication Fails

• Ensure your browser can reach the sign-in page
• For SaaS: check that app.teamloop.io is accessible
• For Marketplace: check that the Cognito hosted UI domain is accessible

”Unauthorized” After Sign-In (Marketplace)

• Verify the user exists in the Cognito User Pool
• Check that the MCP CLI app client (CognitoMCPClientId in stack outputs) is correctly configured
• Ensure the callback URL http://localhost:9876/callback is not blocked by a firewall

Token Refresh Failures

• Access tokens expire after 1 hour and refresh automatically
• If refresh fails, remove the stored token and re-authenticate
• For Marketplace: check CloudWatch logs at /ecs/STACK_NAME/api for auth errors

Debug Logging

Enable debug logs to diagnose issues:

{
  "mcpServers": {
    "teamloop": {
      "command": "npx",
      "args": ["-y", "@teamloop/mcp-server"],
      "env": {
        "TEAMLOOP_LOG_LEVEL": "debug"
      }
    }
  }
}

Next Steps

• MCP Tools Reference - Learn all available tools
• Query Playground - Start making queries