Tellen Setup

Help the user connect Claude to their Tellen workspace via MCP.

Prerequisites

The user needs a Tellen account with an active workspace. If they don't have one, direct them to https://tellen.ai.

Setup Steps

1. Get the Tellen URL

Ask the user for their Tellen workspace URL. It will be one of:

• •https://app.tellen.ai (production)
• •A custom deployment URL (e.g., https://customer.tellen.ai)

2. Create OAuth Credentials

Direct the user to create an OAuth client:

1. •Go to Settings → Agent MCP & API Access in their Tellen workspace
2. •Click Create OAuth Client
3. •Name it "Claude Desktop" or "Claude Code"
4. •Select the MCP Full Access scope (or specific scopes if they want to limit access)
5. •Click Create Client and copy the client secret immediately (it won't be shown again)
6. •Note the Client ID from the table

3. Get an Access Token

Run the following command, replacing the placeholders:

curl -X POST {TELLEN_URL}/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}"

This returns a JSON response with an access_token (valid for 30 minutes).

4. Set Environment Variables

The user needs to set two environment variables:

export TELLEN_URL="https://app.tellen.ai"  # or their custom URL
export TELLEN_ACCESS_TOKEN="the_access_token_from_step_3"

For persistent configuration, add these to their shell profile (~/.zshrc, ~/.bashrc, etc.).

5. Verify Connection

After setup, test the connection by using one of the Tellen MCP tools:

• •Try search_files with a simple query
• •Try research_us_gaap with a question like "How are leases classified under ASC 842?"

Troubleshooting

• •Token expired: Access tokens expire after 30 minutes. Re-run the curl command from step 3 to get a fresh token and update TELLEN_ACCESS_TOKEN.
• •401 Unauthorized: Check that the client ID and secret are correct, and that the OAuth client has the required scopes.
• •Connection refused: Verify the TELLEN_URL is correct and accessible from this machine.

Token Refresh

When the token expires, the user can refresh it by running the curl command again. For automation, they can create a shell alias:

alias tellen-refresh='export TELLEN_ACCESS_TOKEN=$(curl -s -X POST $TELLEN_URL/api/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=$TELLEN_CLIENT_ID" -d "client_secret=$TELLEN_CLIENT_SECRET" | jq -r .access_token)'