MCP Setup Guide

MCP Setup Guide

This guide walks you through setting up the Transactional MCP server with Claude Desktop and Claude Code.

Prerequisites

• A Transactional account
• Claude Desktop or Claude Code installed
• The Transactional CLI installed (optional, for automated setup)

How Authentication Works

Transactional MCP uses OAuth 2.1 for authentication, following the MCP Authorization specification. This means:

• No tokens in config files - Your credentials are never stored in plain text
• Secure browser-based login - You authenticate through your browser
• Automatic token refresh - Claude handles token management

When you first use Transactional tools, Claude will prompt you to authorize access to your Transactional account through your browser.

Method 1: Claude Desktop (Pro/Max/Team/Enterprise)

For paid Claude plans, you can add remote MCP servers directly through the UI:

Step 1: Open Settings

In Claude Desktop, go to Settings → Integrations

Step 2: Add Custom Integration

Click "+ Add Custom Integration" and enter:

https://mcp.usetransactional.com

Step 3: Authorize

When you first use a Transactional tool, Claude will open your browser to complete OAuth authorization. Log in with your Transactional account and approve access.

That's it! Claude handles the OAuth flow automatically.

Method 2: Claude Desktop (Free/JSON Config)

For free-tier users or those who prefer JSON configuration, use the mcp-remote wrapper:

Step 1: Install mcp-remote

npm install -g mcp-remote

Step 2: Install via CLI (Recommended)

transactional mcp install --target claude-desktop

This creates the proper configuration automatically.

Step 3: Manual Configuration (Alternative)

Edit your Claude Desktop config file:

Add the following configuration:

{
  "mcpServers": {
    "transactional": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.usetransactional.com"]
    }
  }
}

Step 4: Restart and Authorize

Restart Claude Desktop. When you first use a Transactional tool, you'll be prompted to authorize through your browser.

Method 3: Claude Code

Claude Code supports remote MCP servers with OAuth directly.

Step 1: Install via CLI (Recommended)

transactional mcp install --target claude-code

Step 2: Manual Configuration (Alternative)

Edit ~/.claude.json:

{
  "mcpServers": {
    "transactional": {
      "url": "https://mcp.usetransactional.com/mcp"
    }
  }
}

Step 3: Authorize

When you first use a Transactional tool in Claude Code, you'll be prompted to authorize through your browser.

Install to Both

To install for both Claude Desktop and Claude Code at once:

transactional mcp install

Or explicitly:

transactional mcp install --target both

Verify Installation

Check Status

transactional mcp status

Ask Claude

In Claude Desktop or Code, ask: "What Transactional tools do you have access to?"

OAuth Flow Details

The authorization flow follows the MCP OAuth 2.1 specification:

1. Initial Request: Claude makes a request to the MCP server
2. 401 Challenge: Server returns 401 with WWW-Authenticate header containing the Protected Resource Metadata URL
3. Metadata Discovery: Claude fetches OAuth metadata from /.well-known/oauth-protected-resource
4. Authorization: Claude redirects you to the authorization endpoint
5. Login: You log in to Transactional and approve access
6. Token Exchange: Claude exchanges the authorization code for an access token
7. Authenticated Requests: Subsequent requests include the access token

OAuth Endpoints

Managing Installation

Update Configuration

transactional mcp install --force

Uninstall

transactional mcp uninstall

Or for a specific target:

transactional mcp uninstall --target claude-desktop
transactional mcp uninstall --target claude-code

Self-Hosted Instances

For self-hosted Transactional installations:

# Configure CLI for your instance
transactional config set apiUrl https://api.yourinstance.com
 
# Install MCP config
transactional mcp install

The CLI will automatically use your configured API URL for the MCP server.

Next Steps

• Available Tools - See all MCP tools
• Troubleshooting - Fix common issues
• Claude Code Guide - Claude Code specific features

Sources

• MCP Authorization Specification
• MCP Transports
• Building Custom Connectors via Remote MCP Servers