Connect to MCP

Overview

This guide will walk you through connecting your AI tools (like Cursor or Claude Desktop) to your Unli AI workspace using the Model Context Protocol (MCP). This connection enables AI agents to search and interact with your workspace data.

Prerequisites

Before you begin, ensure you have:

• An active Unli.ai account
• A workspace with data indexed
• Access to create API tokens in your Unli.ai account
• An MCP-compatible AI tool (Cursor, Claude Desktop, etc.)

Step 1: Create an API Token

To connect via MCP, you'll need to create an API token with the appropriate permissions.

Obtaining Your Token

1. Log in to your Unli.ai account
2. Navigate to Settings → API Tokens
3. Click Create New Token
4. Configure your token:
   • Name: Give it a descriptive name (e.g., "MCP - Cursor")
   • Permissions: Select the following scopes:
     • read - Allows reading workspace data
     • mcp.read - Enables MCP server access
5. Click Create Token
6. Important: Copy your token immediately - it won't be shown again!

Step 2: Get Your Workspace ID

You'll need your workspace ID to complete the connection:

1. Navigate to your workspace in Unli.ai
2. Find your workspace ID in the URL or workspace settings
3. Copy the workspace ID for use in the configuration below

Step 3: Configure Your AI Tool

Choose the configuration method that matches your AI tool.

General Configuration

Most MCP-compatible tools support this standard configuration format:

Option A: Workspace ID in URL (Recommended)

{
  "mcpServers": {
    "Unli AI": {
      "url": "https://unli.ai/mcp?workspace=<workspace_id>",
      "headers": {
        "Authorization": "Bearer <your_unli_token>"
      }
    }
  }
}

Option B: Workspace ID in Header

If you prefer to keep the workspace ID out of the URL, you can pass it as a header:

{
  "mcpServers": {
    "Unli AI": {
      "url": "https://unli.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your_unli_token>",
        "workspace": "<workspace_id>"
      }
    }
  }
}

Configuration Parameters:

• url: The Unli AI MCP server endpoint
• workspace: Your unique workspace identifier
• Authorization: Your API token with Bearer prefix
• Unli AI: The display name for this MCP server (can be customized)

Tool-Specific Configurations

Cursor

Cursor uses the standard MCP configuration format. To set it up:

1. Open Cursor
2. Go to Settings → Model Context Protocol
3. Add a new MCP server configuration:

{
  "mcpServers": {
    "Unli AI": {
      "url": "https://unli.ai/mcp?workspace=<workspace_id>",
      "headers": {
        "Authorization": "Bearer <your_unli_token>"
      }
    }
  }
}

4. Replace <workspace_id> with your actual workspace ID
5. Replace <your_unli_token> with your API token
6. Save the configuration
7. Restart Cursor if necessary

Claude Desktop

Claude Desktop requires the mcp-remote package to connect to remote MCP servers. Use this configuration:

1. Open your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
2. Add the following configuration:

{
  "mcpServers": {
    "unli-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://unli.ai/mcp?workspace=<workspace_id>",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your_unli_token>"
      }
    }
  }
}

3. Replace <workspace_id> with your actual workspace ID
4. Replace <your_unli_token> with your API token
5. Save the file
6. Restart Claude Desktop

Note: This configuration uses npx to run mcp-remote, which proxies the remote MCP server. The first run may take a moment as it downloads the package.

Step 4: Verify the Connection

After configuring your AI tool, verify that the connection is working:

1. Open your AI tool (Cursor or Claude Desktop)
2. Look for the Unli AI MCP server in the available tools/servers list
3. Try a test query like: "Search my workspace for documentation about..."
4. Confirm that you receive results from your Unli workspace

Troubleshooting

Common Issues

Connection Failed

• Cause: Invalid token or incorrect URL
• Solution:
  • Verify your token has read and mcp.read permissions
  • Check that your workspace ID is correct
  • Ensure the token hasn't expired

No Results Returned

• Cause: Empty workspace or incorrect workspace ID
• Solution:
  • Confirm your workspace has indexed documents
  • Verify the workspace ID in your configuration
  • Check that your token has access to the specified workspace

Authentication Error

• Cause: Token format incorrect or missing Bearer prefix
• Solution:
  • Ensure your token starts with Bearer (note the space)
  • Check for any extra spaces or characters in the token
  • Regenerate the token if necessary

Claude Desktop: Command Not Found

• Cause: npx or node not installed
• Solution:
  • Install Node.js from nodejs.org
  • Restart Claude Desktop after installation
  • Verify npx is in your system PATH

Getting Help

If you continue to experience issues:

• Check the Unli AI status page for service interruptions
• Review your API token permissions
• Contact Unli.ai support with your configuration (excluding sensitive tokens)

Security Best Practices

• Never share your API tokens publicly or commit them to version control
• Use environment variables for tokens when possible
• Rotate tokens regularly for enhanced security
• Create separate tokens for different tools or use cases
• Revoke tokens immediately if compromised
• Use minimum required permissions - only add scopes you need

What's Next?

Once connected, you can:

• Search your workspace directly from your AI tool
• Ask questions about your documented knowledge
• Retrieve specific information from your data sources
• Leverage AI assistance with access to your workspace context

Learn more about available MCP tools and security considerations.

Ready to Supercharge Your AI Tools?
Connect your workspace and unlock the power of context-aware AI assistance!