NextAgency-MCP

swosei/NextAgency-MCP

3.2

If you are the rightful owner of NextAgency-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This is an unofficial, community-maintained MCP server for NextAgency's API, providing a lightweight, multi-tenant server with OAuth2 authentication.

Tools
47
Resources
0
Prompts
0

NextAgency-MCP

Note: This is an unofficial, community-maintained MCP server for NextAgency's API. It is not officially supported by NextAgency.

A lightweight, multi-tenant MCP server that exposes NextAgency's API as MCP tools with OAuth2 authentication and automatic token refresh.

Features

Setup & Security

  • Dead-Simple Setup - Get running in 2 commands
  • Secure OAuth2 - Authorization code flow with automatic refresh
  • OS Keychain Storage - Tokens encrypted in your system keychain

Capabilities

  • Multi-Tenant - Supports any {tenant}.nextbroker.io or {tenant}.nextbroker.info subdomain
  • 45+ MCP Tools - Full CRUD for Cases, Contacts, Tasks, Notes, Employees, Benefits, Carriers, Sub-Agents, Addresses, and VOIP
  • Web UI - Built-in Setup Wizard and Tool Explorer

Integrations

  • Auto-Configure - One-click setup for Cursor, Claude Desktop, VS Code MCP, Claude Code CLI, and Continue.dev

Quick Start

Installation (2 commands)

git clone https://github.com/your-org/NextAgency-MCP.git
cd NextAgency-MCP
npm run setup

That's it! The Web UI will open automatically at http://localhost:8787

Setup Wizard

The Web UI guides you through a simple 4-step process:

  1. Enter Credentials

    • NextAgency tenant subdomain (e.g., yahoo)
    • Base domain (nextbroker.io for production, nextbroker.info for testing)
    • OAuth Client ID and Client Secret

  2. Authorize

    • Click "Next: Authorize" to authenticate with NextAgency
    • Grant permissions to the MCP server

  3. Auto-Configure

    • Setup wizard auto-detects your installed MCP clients
    • Select your client from the dropdown
    • Click "Auto-Configure" for one-click setup

  4. Done!

    • Restart your MCP client
    • Start using NextAgency tools in your AI assistant

Management Commands

# Start all services (Web UI + APIs)
npm run start:all

# Stop all services
npm run stop:all

# View logs
tail -f logs/*.log

# Rebuild after code changes
npm run build

Available Services

Once started, you have access to:

Manual Configuration

If auto-configuration doesn't work, or you're helping an LLM configure the server, use these manual instructions.

Configuration Format by Client

Cursor, Claude Desktop, and Continue.dev

Add this to your client's config file:

{
  "mcpServers": {
    "nextagency": {
      "command": "nextagency-mcp",
      "args": [],
      "env": {
        "NEXTA_CONFIG": "~/.nextagency-mcp/config.json"
      }
    }
  }
}
Claude Code CLI

Add this to ~/.claude.json:

{
  "mcpServers": {
    "nextagency": {
      "command": "nextagency-mcp",
      "args": [],
      "env": {
        "NEXTA_CONFIG": "~/.nextagency-mcp/config.json"
      }
    }
  }
}

Note: Claude Code CLI detection may not work on Linux. If the setup wizard doesn't detect it, manually add the config above to ~/.claude.json.

VS Code MCP (Native MCP Support)

VS Code uses a different format. Add this to your mcp.json file:

{
  "servers": {
    "nextagency": {
      "type": "stdio",
      "command": "nextagency-mcp",
      "args": [],
      "env": {
        "NEXTA_CONFIG": "~/.nextagency-mcp/config.json"
      }
    }
  }
}

To open the config file in VS Code, run: "MCP: Open User Configuration"

Config File Locations by OS

šŸŖŸ Windows
  • Cursor: %APPDATA%\Cursor\User\settings.json
  • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json
  • Claude Code CLI: %USERPROFILE%\.claude.json
  • VS Code MCP: %APPDATA%\Code\User\mcp.json
  • Continue.dev: %USERPROFILE%\.continue\config.json
šŸŽ macOS
  • Cursor: ~/.cursor/config/cursor-settings.json
  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Code CLI: ~/.claude.json
  • VS Code MCP: ~/Library/Application Support/Code/User/mcp.json
  • Continue.dev: ~/.continue/config.json
šŸ§ Linux
  • Cursor: ~/.config/Cursor/User/settings.json or ~/.cursor/config/cursor-settings.json
  • Claude Desktop: ~/.config/Claude/claude_desktop_config.json
  • Claude Code CLI: ~/.claude.json
  • VS Code MCP: ~/.config/Code/User/mcp.json or ~/.config/Code - OSS/User/mcp.json
  • Continue.dev: ~/.continue/config.json

Available Tools

Cases (Businesses)

  • list_cases - List all cases with pagination
  • get_case - Get a specific case by ID
  • search_cases - Search cases by query
  • create_case - Create a new case
  • update_case - Update an existing case

Contacts

  • list_contacts - List all contacts
  • get_contact - Get specific contact
  • search_contacts - Search contacts by query
  • search_contacts_by_phone - Search by phone number
  • create_contact - Create new contact
  • update_contact - Update existing contact

Tasks

  • list_tasks - List tasks for a case
  • get_task - Get specific task
  • search_tasks - Search tasks
  • create_task - Create new task
  • update_task - Update existing task

Notes

  • list_notes - List notes for a case
  • get_note - Get specific note
  • create_note - Create note with attachments
  • update_note - Update existing note

Employees

  • list_employees - List employees for a case
  • get_employee - Get specific employee
  • search_employees - Search employees
  • create_employee - Create new employee
  • update_employee - Update existing employee

VOIP Recordings

  • list_voip_recordings - List all VOIP recordings
  • get_voip_recording - Get specific recording
  • search_voip_by_referenceable - Search by Business or Contact
  • create_voip_recording - Create new recording

Benefits

  • list_benefits - List benefits for a case
  • get_benefit - Get specific benefit
  • create_benefit - Create new benefit
  • update_benefit - Update existing benefit

Carriers

  • list_carriers - List all carriers
  • get_carrier - Get specific carrier
  • search_carriers - Search carriers
  • create_carrier - Create new carrier
  • update_carrier - Update existing carrier

Sub-Agents

  • list_sub_agents - List all sub-agents
  • get_sub_agent - Get specific sub-agent
  • search_sub_agents - Search sub-agents
  • create_sub_agent - Create new sub-agent
  • update_sub_agent - Update existing sub-agent

Addresses

  • list_addresses - List all addresses
  • get_address - Get specific address
  • update_address - Update existing address

System

  • check_auth_status - Check authentication status and token expiry

Authentication

NextAgency-MCP uses OAuth2 authorization code flow:

  1. Authorization - User visits /oauth/authorize to grant access
  2. Token Exchange - Authorization code is exchanged for access + refresh tokens
  3. Secure Storage - Tokens are encrypted in OS keychain (via Keytar)
  4. Auto-Refresh - Access tokens are automatically refreshed before expiry
  5. 401 Retry - Failed requests are retried once after refreshing token

Configuration Storage

Configuration is stored in ~/.nextagency-mcp/config.json:

{
  "tenant": "yahoo",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8787/callback",
  "baseUrl": "nextbroker.io"
}

Tokens are NEVER stored in this file - they're encrypted in your OS keychain.

Troubleshooting

Services won't start

Check if ports are already in use:

lsof -i :8787  # Web UI
lsof -i :8788  # Tool Explorer API
lsof -i :8789  # Setup Wizard API

Stop all services and try again:

npm run stop:all
npm run start:all

"No configuration found"

Run the setup wizard:

npm run start:all
# Visit http://localhost:8787

"Not authenticated"

Your tokens may have expired. Re-run the setup wizard to re-authenticate:

npm run start:all
# Visit http://localhost:8787

"Failed to refresh token"

Your refresh token has expired. Re-authenticate through the setup wizard.

MCP client can't find the server

Make sure nextagency-mcp is in your PATH after building:

npm run build
cd server
npm link

Verify it's accessible:

which nextagency-mcp

Check if services are running

# Check PIDs
cat .pids/*.pid

# Check logs
tail -f logs/*.log

# Test services directly
curl http://localhost:8787  # Web UI
curl http://localhost:8788/api/health  # Tool Explorer
curl http://localhost:8789/api/health  # Setup Wizard

For LLMs Helping Users

When helping users set up NextAgency-MCP, use these commands:

First-time setup

npm run setup

Start services

npm run start:all

Stop services

npm run stop:all

Check status

# Check if services are running
curl http://localhost:8787
curl http://localhost:8788/api/health
curl http://localhost:8789/api/health

# View logs
tail -f logs/*.log

Direct users to the Web UI

Always direct users to http://localhost:8787 for setup. The wizard handles everything automatically.

Manual configuration

If auto-configure doesn't work, use the config file paths listed in "Config File Locations by OS" above. Remember:

  • VS Code MCP uses servers format with type: "stdio"
  • Claude Code CLI uses mcpServers format (may not auto-detect on Linux)
  • All other clients use mcpServers format

Test the server

After configuration, test in the Tool Explorer:

http://localhost:8787/explorer

Development

# Install dependencies
npm install

# Run server in dev mode
npm run dev --workspace=server

# Run web UI in dev mode
npm run dev --workspace=web

# Build all workspaces
npm run build

# Run tests
npm test

Project Structure

NextAgency-MCP/
ā”œā”€ā”€ server/               # MCP server implementation
ā”‚   ā”œā”€ā”€ src/
ā”‚   ā”‚   ā”œā”€ā”€ auth/         # OAuth2 + token management
ā”‚   ā”‚   ā”œā”€ā”€ api/          # NextAgency API client
ā”‚   ā”‚   ā”œā”€ā”€ mcp/          # MCP tool definitions
ā”‚   ā”‚   ā”œā”€ā”€ config/       # Configuration management
ā”‚   ā”‚   ā””ā”€ā”€ index.ts      # Entry point
ā”‚   ā””ā”€ā”€ package.json
ā”œā”€ā”€ web/                  # Setup wizard & Tool Explorer
ā”‚   ā”œā”€ā”€ src/
ā”‚   ā”‚   ā”œā”€ā”€ components/   # React components
ā”‚   ā”‚   ā”œā”€ā”€ server.ts     # Setup wizard backend
ā”‚   ā”‚   ā”œā”€ā”€ api-server.ts # Tool Explorer backend
ā”‚   ā”‚   ā””ā”€ā”€ main.tsx
ā”‚   ā””ā”€ā”€ package.json
ā”œā”€ā”€ scripts/              # Setup and management scripts
ā”‚   ā”œā”€ā”€ install.sh        # Installation script
ā”‚   ā”œā”€ā”€ setup.sh          # Complete setup (install + start)
ā”‚   ā”œā”€ā”€ start-all.sh      # Start all services
ā”‚   ā””ā”€ā”€ stop-all.sh       # Stop all services
ā””ā”€ā”€ package.json          # Root workspace config

Security

  • āœ… Tokens encrypted in OS keychain
  • āœ… No tokens in config files or logs
  • āœ… Automatic token refresh
  • āœ… HTTPS only for API calls
  • āœ… Strict endpoint allowlist

API Documentation

See the NextAgency API Documentation for detailed endpoint specifications.

Contributing

Contributions are welcome! Please open an issue or PR.

License

MIT

Support

For issues or questions, please open a GitHub issue.