MCP Setup Guide¶

This guide walks you through setting up MCP integration to connect AI assistants with Asset Optics.

Prerequisites¶

Before setting up MCP:

Asset Optics account with at least one project
One of the supported AI tools installed:
Claude Desktop
Cursor
VS Code with MCP extension
Internet connection

Step 1: Generate an MCP Token¶

Via Web Dashboard¶

Go to asset-optics.brahmaforge.com
Sign in with your account
Click your profile avatar → Account Settings
Navigate to API Access
Click Generate MCP Token
Copy the generated configuration

Token Configuration¶

The generated configuration looks like this:

{
  "mcpServers": {
    "asset-optics": {
      "command": "npx",
      "args": ["-y", "@brahmaforge/asset-optics-mcp"],
      "env": {
        "AO_ACCESS_TOKEN": "your-access-token-here",
        "AO_REFRESH_TOKEN": "your-refresh-token-here"
      }
    }
  }
}

Keep Tokens Secure

Never share your tokens publicly. They provide access to your Asset Optics account.

Step 2: Configure Your AI Tool¶

Claude Desktop¶

Open Claude Desktop
Go to Settings (Cmd/Ctrl + ,)
Navigate to Developer → MCP Servers
Click Edit Config or open the config file directly

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Asset Optics configuration:

{
  "mcpServers": {
    "asset-optics": {
      "command": "npx",
      "args": ["-y", "@brahmaforge/asset-optics-mcp"],
      "env": {
        "AO_ACCESS_TOKEN": "your-access-token-here",
        "AO_REFRESH_TOKEN": "your-refresh-token-here"
      }
    }
  }
}

Save the file
Restart Claude Desktop

Cursor¶

Open Cursor
Go to Settings (Cmd/Ctrl + ,)
Search for "MCP" in settings
Find the MCP configuration section
Add the Asset Optics configuration
Restart Cursor

VS Code¶

Install an MCP-compatible extension
Open VS Code settings (Cmd/Ctrl + ,)
Search for the MCP configuration section
Add the Asset Optics configuration
Reload VS Code

Step 3: Test the Connection¶

After configuration:

Open your AI assistant
Ask: "List my Asset Optics projects"
The AI should respond with your project list

If successful, you'll see your projects listed. If not, see Troubleshooting below.

Managing Tokens¶

Viewing Active Tokens¶

Go to Account Settings → API Access
See a list of all generated tokens
Each token shows:
Name/identifier
Creation date
Last used date

Revoking Tokens¶

To revoke a token:

Go to Account Settings → API Access
Find the token in the list
Click Revoke
Confirm the revocation

Note

Revoking a token immediately stops it from working. Update your AI tool configuration if you revoke an active token.

Rotating Tokens¶

For security, periodically rotate your tokens:

Generate a new token
Update your AI tool configuration
Revoke the old token
Test the new token

Security Best Practices¶

Token Security¶

Keep tokens private: Never share or commit tokens to version control
Use per-device tokens: Generate separate tokens for each device
Rotate regularly: Generate new tokens every few months
Revoke unused tokens: Delete tokens you no longer use

Network Security¶

MCP communication is encrypted
Tokens are transmitted securely
Refresh tokens handle session management

Audit Trail¶

All MCP actions are logged:

View action history in the web dashboard
See what AI requested and when
Track approved and rejected plans

Troubleshooting¶

"Connection Failed" Error¶

Possible causes:

Invalid or expired token
Network connectivity issues
MCP server not running

Solutions:

Generate a new token and update configuration
Check your internet connection
Restart your AI tool
Verify the configuration JSON is valid

AI Can't See Projects¶

Possible causes:

Wrong account token
Token permissions issue
Network blocking

Solutions:

Verify you're using the correct account
Generate a fresh token
Check firewall settings

Plans Not Appearing¶

Possible causes:

Plan expired (30-minute timeout)
Plugin not refreshed
Sync delay

Solutions:

Refresh the Asset Optics panel
Check the web dashboard for pending plans
Ask the AI to recreate the plan

Token Expired¶

Symptoms:

"Unauthorized" errors
AI can't complete actions

Solution:

Generate a new token
Update your AI tool configuration
Restart the AI tool

Advanced Configuration¶

Multiple Accounts¶

If you have multiple Asset Optics accounts:

{
  "mcpServers": {
    "asset-optics-personal": {
      "command": "npx",
      "args": ["-y", "@brahmaforge/asset-optics-mcp"],
      "env": {
        "AO_ACCESS_TOKEN": "personal-token",
        "AO_REFRESH_TOKEN": "personal-refresh"
      }
    },
    "asset-optics-work": {
      "command": "npx",
      "args": ["-y", "@brahmaforge/asset-optics-mcp"],
      "env": {
        "AO_ACCESS_TOKEN": "work-token",
        "AO_REFRESH_TOKEN": "work-refresh"
      }
    }
  }
}

Environment Variables¶

Instead of putting tokens in the config file, use environment variables:

{
  "mcpServers": {
    "asset-optics": {
      "command": "npx",
      "args": ["-y", "@brahmaforge/asset-optics-mcp"],
      "env": {
        "AO_ACCESS_TOKEN": "${AO_ACCESS_TOKEN}",
        "AO_REFRESH_TOKEN": "${AO_REFRESH_TOKEN}"
      }
    }
  }
}

Then set the environment variables in your shell profile.