Skip to content
  • mcp
  • setup

MCP Setup

MCP Setup Guide

Section titled “MCP Setup Guide”

TeamLoop uses the Model Context Protocol (MCP) to connect with AI assistants like Claude. This guide covers all setup options.

What is MCP?

Section titled “What is MCP?”

MCP is an open standard for connecting AI assistants to external tools and data sources. It allows:

  • Secure, authenticated connections
  • Structured tool interfaces
  • Streaming responses
  • Cross-platform compatibility

Claude Desktop Setup

Section titled “Claude Desktop Setup”

Claude Desktop is the most common MCP client. Here’s how to configure it.

Step 1: Locate Config File

Section titled “Step 1: Locate Config File”

The configuration file location varies by platform:

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

Step 2: Add TeamLoop Server

Section titled “Step 2: Add TeamLoop Server”

Add TeamLoop to your mcpServers configuration:

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

Step 3: Get API Key

Section titled “Step 3: Get API Key”
  1. Log into app.teamloop.io
  2. Go to Settings > API Keys
  3. Click Create API Key
  4. Copy the key (it starts with tl_)

Step 4: Restart Claude

Section titled “Step 4: Restart Claude”

Completely quit and restart Claude Desktop to load the new configuration.

Configuration Options

Section titled “Configuration Options”

Environment Variables

Section titled “Environment Variables”
VariableRequiredDescription
TEAMLOOP_API_KEYYesYour TeamLoop API key
TEAMLOOP_API_URLNoCustom API URL (for self-hosted)
TEAMLOOP_LOG_LEVELNoLogging level (debug, info, warn, error)

Full Configuration Example

Section titled “Full Configuration Example”
{
  "mcpServers": {
    "teamloop": {
      "command": "npx",
      "args": ["-y", "@teamloop/mcp-server"],
      "env": {
        "TEAMLOOP_API_KEY": "tl_your_api_key_here",
        "TEAMLOOP_LOG_LEVEL": "info"
      }
    }
  }
}

Self-Hosted Deployment

Section titled “Self-Hosted Deployment”

If you’re running TeamLoop on your own infrastructure:

{
  "mcpServers": {
    "teamloop": {
      "command": "npx",
      "args": ["-y", "@teamloop/mcp-server"],
      "env": {
        "TEAMLOOP_API_KEY": "your-key",
        "TEAMLOOP_API_URL": "https://your-teamloop-instance.com/api"
      }
    }
  }
}

Using with Claude Code

Section titled “Using with Claude Code”

If you’re using Claude Code (CLI), add TeamLoop to your project’s .mcp.json:

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

Then set the environment variable:

Terminal window
export TEAMLOOP_API_KEY="tl_your_api_key_here"

Using with Other MCP Clients

Section titled “Using with Other MCP Clients”

TeamLoop works with any MCP-compatible client. The server follows the MCP 2024-11-05 specification.

Server Details

Section titled “Server Details”
  • Protocol: JSON-RPC over stdio
  • Protocol Version: 2024-11-05
  • Capabilities: tools

Direct Invocation

Section titled “Direct Invocation”

You can run the MCP server directly:

Terminal window
TEAMLOOP_API_KEY=your-key npx @teamloop/mcp-server

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

Verifying Setup

Section titled “Verifying Setup”

After configuration, verify TeamLoop is working:

  1. Start a new conversation in Claude
  2. Ask: “What TeamLoop tools are available?”
  3. Claude should list the TeamLoop tools

If Claude doesn’t see the tools:

  • Check the config file syntax
  • Verify the API key is correct
  • Check Claude’s logs for errors

Security Best Practices

Section titled “Security Best Practices”

API Key Management

Section titled “API Key Management”
  • Never commit API keys to version control
  • Use environment variables when possible
  • Rotate keys periodically in TeamLoop settings
  • Create separate keys for different environments

Permissions

Section titled “Permissions”

TeamLoop respects OAuth permissions:

  • Only accesses tools you’ve connected
  • Only sees data you’ve authorized
  • Doesn’t store credentials, only tokens

Troubleshooting

Section titled “Troubleshooting”

”Server not found” Error

Section titled “”Server not found” Error”
  • Ensure Node.js 18+ is installed
  • Try running npx @teamloop/mcp-server manually
  • Check network connectivity

”Invalid API Key” Error

Section titled “”Invalid API Key” Error”
  • Verify the key in TeamLoop settings
  • Check for typos or extra whitespace
  • Ensure the key hasn’t been revoked

Connection Timeouts

Section titled “Connection Timeouts”
  • Check your network connection
  • Verify TeamLoop service status
  • Try increasing timeout in config

Debug Logging

Section titled “Debug Logging”

Enable debug logs to diagnose issues:

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

Next Steps

Section titled “Next Steps”