MCP Tokens - Authentication & Security

Learn how MCP tokens authenticate AI assistants and secure your Contextium workspace access.

---

What Are MCP Tokens?

MCP tokens are secure authentication credentials that allow AI assistants (like Claude, ChatGPT, Cursor) to access your Contextium documentation on your behalf.

Think of Tokens Like House Keys

• Your password = Master key to your house
• MCP token = Copy you give to a trusted service (like a dog walker)
• Revoke token = Take back the key anytime
• Token expiry = Key stops working after a certain date

How They Work

You → Generate Token → Give to Claude → Claude reads your docs

1. You create a token in Contextium settings
2. Token is saved to ~/.doxhub/credentials.json
3. Claude uses token to authenticate API requests
4. Contextium verifies token and returns your documentation
5. You can revoke token anytime to stop access

---

Token vs Password: Key Differences

Key point: Tokens are safer than passwords because they're limited, expiring, and revocable.

---

Token Security Model

Individual User Tokens

Each person gets their own token - tokens are never shared between team members.

Why?

• Audit trail - Know who accessed what
• Individual revocation - Remove one person's access without affecting others
• No shared secrets - If someone leaves, just revoke their token
• Permission isolation - Each user's token respects their workspace role

Example:

Owner generates token → Can access "Company Workspace"
Team member generates token → Can also access "Company Workspace"
(Both use different tokens, same workspace access)

Token Authentication Flow

1. User runs: npx @contextium/mcp-server@latest setup
2. Browser opens → User logs in
3. User selects workspace and authorizes
4. Token generated and linked to:
   - User account (who)
   - Workspace (where)
   - Device (what)
   - Expiry date (when)
5. Token saved to ~/.doxhub/credentials.json
6. Claude uses token for all requests
7. Contextium checks:
   - Is token valid? (not expired/revoked)
   - Does user have workspace access?
   - Does user have permission for this action?
8. Request succeeds or fails based on checks

---

Token Lifecycle

1. Creation

Automatic (Recommended):

npx @contextium/mcp-server@latest setup

Manual (Advanced):

1. Go to Settings → MCP Tokens
2. Expand "For VS Code / Cursor / Other Tools"
3. Click "Generate New Token"
4. Select workspace and expiry
5. Copy token and save to credentials file

2. Active Use

While active, tokens:

• Authenticate all MCP requests
• Track last used timestamp
• Respect user's workspace permissions
• Update session activity

View active tokens:

• Go to Settings → MCP Tokens
• See device name, created date, last used, expiry

3. Expiry

Default expiry: 90 days (configurable 30-365 days)

Why tokens expire:

• Security best practice (like changing passwords)
• Prevents abandoned tokens from staying active
• Forces periodic re-authorization

When token expires:

• Claude stops working with Contextium
• You get error: "Token has expired"
• Solution: Generate new token or extend existing one

Expiry warnings:

• Email notification 30 days before expiry
• Warning badge in Settings → MCP Tokens
• "Extend" button appears when < 30 days left

4. Extension

When to extend:

• Token expiring soon (< 30 days)
• Still actively using Claude with Contextium
• Don't want to reconfigure

How to extend:

1. Go to Settings → MCP Tokens
2. Find token with warning
3. Click "Extend" button
4. Adds 90 more days to expiry
5. No reconfiguration needed

When NOT to extend:

• Token compromised → Revoke and create new one
• Changing workspaces → Create new token
• Device no longer used → Revoke instead

5. Revocation

When to revoke:

• Token compromised or exposed
• Device lost or stolen
• No longer using Claude with Contextium
• Team member leaves organization
• Switching to different workspace

How to revoke:

1. Go to Settings → MCP Tokens
2. Find token to revoke
3. Click "Revoke" button
4. Confirm

Effects of revocation:

• Token stops working immediately
• Claude gets 401 Unauthorized errors
• Must generate new token to restore access
• Cannot undo revocation

---

Token Expiry Options

Choosing Expiry Duration

30 Days:

• Maximum security
• Good for testing
• Frequent renewals needed

60 Days:

• High security
• Reasonable renewal frequency

90 Days (Recommended):

• Balanced security and convenience
• Quarterly renewal matches common practices
• Default for automatic setup

180 Days:

• Less frequent renewals
• Longer exposure if compromised

365 Days (1 Year):

• Convenient for stable setups
• Highest risk if compromised
• Easy to forget about

Best Practices

For Claude Desktop (non-technical users):

• Use automatic setup → Gets 90 days automatically
• Extend when warned → Click "Extend" button
• No need to choose expiry

For VS Code/Cursor (technical users):

• Choose 90 days for most use cases
• Choose 30 days for testing/experiments
• Choose 180-365 days only if you'll remember to renew

For high-security environments:

• Use 30-60 day expiry
• Enable calendar reminders
• Rotate tokens regularly

---

Managing Multiple Tokens

Multiple Devices

You can have multiple tokens active:

• MacBook → Token 1
• Work laptop → Token 2
• Desktop → Token 3

Benefits:

• Each device has its own token
• Revoke individual devices without affecting others
• See which device last accessed docs

How it works:

# On MacBook
npx @contextium/mcp-server@latest setup

# On work laptop
npx @contextium/mcp-server@latest setup

# Each gets a separate token
# Both work independently

Multiple Workspaces

Use profiles for different workspaces:

# Personal workspace
npx @contextium/mcp-server@latest setup --profile personal

# Work workspace
npx @contextium/mcp-server@latest setup --profile work

# Switch between them
npx @contextium/mcp-server switch personal
npx @contextium/mcp-server switch work

Each profile has:

• Separate token
• Different workspace
• Independent expiry
• Own configuration

---

Token Security Best Practices

DO: Secure Token Storage

Credentials stored at: ~/.doxhub/credentials.json File permissions: 600 (owner read/write only) Never commit credentials to Git Add to .gitignore:

.doxhub/
credentials.json

DO: Monitor Token Usage

Check Settings → MCP Tokens regularly Review "Last Used" timestamps Revoke unused tokens Watch for suspicious activity

DO: Rotate Tokens Regularly

Extend tokens before expiry (if still using) Revoke and regenerate every 3-6 months Revoke immediately if device lost

DON'T: Share Tokens

Never share tokens with teammates (they get their own) Don't email tokens Don't paste in Slack/chat Don't screenshot credentials file

DON'T: Ignore Warnings

Don't ignore expiry warnings Don't let tokens expire unexpectedly Don't leave revoked tokens in credentials file

---

Common Scenarios

Scenario 1: Setting Up New Device

Steps:

1. Run npx @contextium/mcp-server@latest setup on new device
2. Authorize in browser
3. New token created automatically
4. Old device token remains active

Result: Two tokens, both work independently

---

Scenario 2: Team Member Joins

Steps:

1. Invite user to workspace (if not already member)
2. User runs npx @contextium/mcp-server@latest setup
3. User authorizes and gets their own token
4. User can now access workspace docs via Claude

Important: Don't share your token - each person gets their own!

---

Scenario 3: Team Member Leaves

Steps:

1. Remove user from workspace (Settings → Team)
2. User's tokens automatically stop working
3. OR: Revoke their MCP token specifically (Settings → MCP Tokens)

Result: User loses access immediately

---

Scenario 4: Device Lost/Stolen

Immediate action:

1. Go to Settings → MCP Tokens
2. Find token for lost device
3. Click "Revoke"
4. Token stops working within seconds

Then:

• Change your Contextium password (if device had saved password)
• Monitor audit logs for suspicious activity
• Generate new token on replacement device

---

Scenario 5: Token Expiring Soon

Warning appears:

• "Token expires in 15 days"
• Orange warning in Settings → MCP Tokens

Option A: Extend (if still using)

1. Click "Extend" button
2. Adds 90 more days
3. No reconfiguration needed

Option B: Regenerate (if need fresh start)

1. Run npx @contextium/mcp-server@latest setup
2. New token replaces old one
3. Old token auto-revoked

---

Scenario 6: Switching Workspaces

If you work in multiple workspaces:

# Setup profile for each workspace
npx @contextium/mcp-server@latest setup --profile personal
npx @contextium/mcp-server@latest setup --profile work

# Switch between them
npx @contextium/mcp-server switch personal  # Use personal workspace
npx @contextium/mcp-server switch work      # Use work workspace

# List all profiles
npx @contextium/mcp-server profiles

Each profile:

• Has its own token
• Points to different workspace
• Independent expiry
• Easy switching

---

Troubleshooting

"Token has been revoked"

Cause: Token was revoked manually or automatically

Fix:

npx @contextium/mcp-server@latest setup

Generates new token.

---

"Token has expired"

Cause: Token passed expiry date

Fix (Easy): If token hasn't been revoked yet:

1. Go to Settings → MCP Tokens
2. Try clicking "Extend" (may still be available)

Fix (New Token):

npx @contextium/mcp-server@latest setup

---

"Authentication failed"

Possible causes:

1. Token invalid/expired/revoked
2. Credentials file corrupted
3. Wrong workspace selected

Fix:

# Check credentials exist
cat ~/.doxhub/credentials.json

# If empty or corrupt, regenerate
npx @contextium/mcp-server@latest setup

---

"Claude can't see my docs"

Checklist:

• Token exists: cat ~/.doxhub/credentials.json
• Token not expired (check "expiresAt" date)
• User has workspace access
• Claude Desktop restarted after setup

Fix:

# Test token validity
npx @contextium/mcp-server status

# If invalid, regenerate
npx @contextium/mcp-server@latest setup

---

Multiple Tokens in Settings

Is this normal? Yes!

Why multiple tokens:

• Different devices (laptop, desktop)
• Different workspaces (via profiles)
• Old tokens not yet expired
• Testing on different machines

What to do:

• Keep active device tokens
• Revoke unused/old device tokens
• Name tokens clearly (device info shows automatically)

---

Token CLI Commands

Check Token Status

npx @contextium/mcp-server status

Shows:

• Token validity
• Workspace name
• Days until expiry
• Last used date

---

List All Profiles

npx @contextium/mcp-server profiles

Shows all configured workspaces and tokens.

---

Switch Workspace

npx @contextium/mcp-server switch [profile-name]

Changes active workspace without regenerating token.

---

Revoke Current Token

npx @contextium/mcp-server revoke

Revokes current profile's token (also available in web UI).

---

Complete Logout

npx @contextium/mcp-server logout

Revokes token AND deletes credentials file.

---

Credentials File Structure

Location: ~/.doxhub/credentials.json

Format:

{
  "profiles": {
    "default": {
      "apiUrl": "https://api.contextium.io/api/v1",
      "accessToken": "mcp_3adf...",
      "workspaceId": "2e1667b7-...",
      "createdAt": "2026-02-06T10:07:01.406Z",
      "expiresAt": "2026-05-07T10:06:57.000Z"
    },
    "work": {
      "apiUrl": "https://api.contextium.io/api/v1",
      "accessToken": "mcp_8def...",
      "workspaceId": "9c2445a8-...",
      "createdAt": "2026-02-06T11:30:00.000Z",
      "expiresAt": "2026-05-07T11:30:00.000Z"
    }
  },
  "currentProfile": "default"
}

Fields explained:

• apiUrl - Contextium API endpoint
• accessToken - MCP token (starts with mcp_)
• workspaceId - Which workspace token accesses
• createdAt - When token was generated
• expiresAt - When token stops working
• currentProfile - Which profile is active

---

Token vs API Key

You might see two types of authentication in Contextium:

Don't confuse them!

• Use MCP tokens for AI assistants
• Use API keys for custom integrations

---

Audit & Compliance

Tracking Token Usage

What's tracked:

• Token creation date
• Last used timestamp
• Device information
• IP address (on creation)
• User agent

Where to see: Settings → MCP Tokens shows:

• All your active tokens
• When last used
• Device/OS info
• Expiry dates

Compliance Considerations

For security audits:

• All tokens have expiry dates
• Individual audit trails (no shared tokens)
• Revocation takes effect immediately
• Full token lifecycle logged

For team admins:

• See all active MCP tokens in workspace
• Identify which users have active tokens
• Revoke tokens for departed users
• Monitor token usage patterns

---

Advanced: Token Permissions

What MCP Tokens Can Do

Read Access:

• List workspaces
• List projects
• List files (metadata)
• Get file content
• Search documentation
• View version history
• See project structure

What They CANNOT Do:

• Create or edit files
• Delete content
• Manage team members
• Change workspace settings
• Access billing information

Why read-only?

• Safety: AI can't accidentally delete docs
• Security: Compromised token has limited damage
• Simplicity: Read-only reduces complexity

---

FAQ

Do tokens work offline?

No. Tokens authenticate to Contextium's API servers. Internet connection required.

Can I use one token on multiple devices?

Yes, but not recommended. Best practice: One token per device for easier tracking and revocation.

What happens if I delete credentials file?

Token remains active in Contextium, but Claude loses access. Run npx @contextium/mcp-server@latest setup to restore.

Can admin see my token?

No. Tokens are hashed in database. Only token prefix (first 8 chars) is visible for identification.

Does token give access to all workspaces?

No. Token is scoped to specific workspace selected during setup. Use profiles for multiple workspaces.

Can I manually edit credentials.json?

Not recommended. Use CLI commands instead:

• npx @contextium/mcp-server@latest setup - Create new token
• npx @contextium/mcp-server switch - Change workspace

What if someone steals my token?

1. Immediately revoke via Settings → MCP Tokens
2. Check audit logs for unauthorized access
3. Generate new token
4. Change password if device was compromised

Token vs Session: What's the difference?

• Session - Internal record in Contextium database
• Token - The actual credential string you use
• One session = One token
• Revoking token revokes session

---

Security Checklist

Before deployment:

• Understand token lifecycle
• Know how to revoke tokens
• Set appropriate expiry (90 days recommended)
• Add .doxhub/ to .gitignore

Regular maintenance:

• Review active tokens monthly
• Revoke unused device tokens
• Extend tokens before expiry
• Monitor "Last Used" timestamps

When leaving device unattended:

• Lock computer
• Don't save token in clipboard
• Don't screenshot credentials

When device lost/stolen:

• Revoke token immediately
• Change Contextium password
• Review audit logs
• Generate new token on replacement device

---

Next Steps

Set up your first token:

• MCP Integration Guide

Manage existing tokens:

• Settings → MCP Tokens

Get help:

• Troubleshooting Guide
• Support

---

Last updated: February 6, 2026 Questions? Email hello@contextium.io