genudo_mcp

# Genudo MCP Client

[![npm version](https://img.shields.io/npm/v/genudo-mcp-client)](https://www.npmjs.com/package/genudo-mcp-client)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

Genudo is the platform to build AI agents for any communication or sequence-based channel — pipeline-aware agents with integration capabilities and company-knowledge access, all managed from one platform, one inbox, and one analytics dashboard. This lightweight bridge connects [Claude](https://claude.com) and other MCP clients to your Genudo workspace so you can build, run, and improve those agents directly from chat.

> 📖 **Which install is right for you?** See **[CONNECT.md](CONNECT.md)** — every way to connect
> Genudo to Claude (plugin, connector, desktop extension, other MCP clients, remote OAuth),
> weighted by value with copy-paste install commands.

## Overview

Genudo MCP Client bridges the communication gap between Claude Code's stdio-based MCP implementation and Genudo's Streamable HTTP MCP server. This allows you to leverage Genudo's powerful business automation tools directly within your Claude Code conversations.

## Features

Access Genudo's business automation tools directly from Claude Code. The server exposes 29 tools across five areas:

- **📊 Analytics** — account summary, messaging volume stats, AI performance & cost (`get_account_summary`, `get_messaging_stats`, `get_ai_performance`)
- **🔎 Discover** — list pipelines, stages, actions, variables, contacts, opportunities, messages, and knowledge tables; search knowledge; read follow-up configs; valid build options (`list_pipelines`, `list_pipeline_stages`, `list_actions`, `list_variables`, `list_contacts`, `list_opportunities`, `list_messages`, `list_knowledge_tables`, `search_knowledge_table`, `get_stage_followup`, `get_pipeline_options`)
- **🚀 Build** — a guided step-by-step builder plus direct creation of pipelines, stages, variables, webhook actions, follow-up sequences, and knowledge tables (`start_pipeline_journey`, `create_pipeline`, `create_stage`, `create_variable`, `create_action`, `create_followup`, `create_knowledge_table`, `upsert_knowledge_points`)
- **🔧 Update** — tune live pipelines, stages, actions, variables, opportunities (bulk), and follow-ups (`update_pipeline`, `update_stage`, `update_action`, `update_variable`, `update_opportunities`, `update_followup`)
- **🗑️ Delete** — remove knowledge rows by stable id (`delete_knowledge_points`)

### Three workflows to start with

1. **Audit my AI business operations** — Claude pulls your account, messaging, and AI-cost stats and surfaces the top fixes.
2. **Analyze my agent performance** — spot expensive agents, low-completion stages, and actions that aren't triggering.
3. **Create or improve a pipeline** — e.g. "Create a Messenger sales agent for a summer camp; collect name, phone, branch, child age; escalate on special-needs questions."

### Guided instruction editing (built in)

The connector doesn't just expose tools — it teaches the agent *how* to write good agent
instructions, entirely client-side (no extra setup):

- **Guide tools** — `get_instruction_guides` (authoring rules + persona/global + stage
  templates + a token-aware QA checklist) and `get_editing_playbook` (a safe
  load → edit → diff → confirm → push workflow). The agent pulls these on demand.
- **Prompts (slash-commands in any MCP client)** — `edit_instructions`, `build_pipeline`,
  `audit_pipeline`.
- **Safety** — before changing a live agent, the agent reads current text from
  `list_pipelines` / `list_pipeline_stages`, shows you a before/after diff with expected
  impact, and pushes with `update_pipeline` / `update_stage` only after you confirm.

## Quick Start

One command — no clone, no manual config:

```bash
claude mcp add --env GENUDO_TOKEN=YOUR_TOKEN --transport stdio genudo -- npx -y genudo-mcp-client
```

Replace `YOUR_TOKEN` with your Genudo token (**API Keys & Tokens** → **Create token** with the `mcp:use` scope — see [Get Your Token](#step-1-get-your-token)). Restart Claude Code and start using Genudo tools!

## Prerequisites

- Node.js 18.0.0 or higher
- A Genudo account with API access
- Your Genudo token

## Installation

### Recommended: one command

```bash
claude mcp add --env GENUDO_TOKEN=YOUR_TOKEN --transport stdio genudo -- npx -y genudo-mcp-client
```

`npx` fetches and runs the published package — no clone, no local path. Get your token from **API Keys & Tokens** (see below), then restart Claude Code.

### Alternative: from source

For local development or contributions:

```bash
git clone https://github.com/genudo-ai/genudo_mcp.git
cd genudo_mcp
npm install
```

Then configure Claude Code manually (see Configuration section below).

## Configuration

### Step 1: Get Your Token

1. Log in to your [Genudo account](https://app.genudo.ai)
2. In the sidebar, under **Developer**, open **API Keys & Tokens**
3. Click **Create token**
4. Name it (e.g. `claude-mcp`)
5. Under **Scopes**, scroll the list and check **`mcp:use`** (Access MCP server — Streamable HTTP + JSON-RPC tool calls)
6. Pick an **Expiry** (30 days, 90 days, 1 year, or No Expiry)
7. Click **Create token** and copy the token — **it's shown only once**; Genudo keeps only a hashed copy

### Step 2: Connect your MCP client

**Recommended — Claude Code, one command:**

```bash
claude mcp add --env GENUDO_TOKEN=YOUR_TOKEN --transport stdio genudo -- npx -y genudo-mcp-client
```

**Other clients (Codex, Cursor, Windsurf, Claude Desktop):** same package, add this block to the client's MCP config:

```json
{
  "mcpServers": {
    "genudo": {
      "command": "npx",
      "args": ["-y", "genudo-mcp-client"],
      "env": {
        "GENUDO_TOKEN": "your_token_here"
      }
    }
  }
}
```

<details>
<summary>Running from source instead (contributors)</summary>

If you cloned the repo rather than using the published package, point at your local `index.js`:

```json
{
  "mcpServers": {
    "genudo": {
      "command": "node",
      "args": ["/absolute/path/to/genudo_mcp/index.js"],
      "env": { "GENUDO_TOKEN": "your_token_here" }
    }
  }
}
```

Replace the path with where you cloned the repo.
</details>

### Step 3: Restart Claude Code

Exit your current Claude Code session and start a new one:

```bash
# Exit current session
exit

# Start new session
claude
```

## Usage

Once configured, Claude Code will automatically have access to your Genudo tools. You can use them in your conversations:

**Example:**
```
User: "Show me my account summary"
Claude: [Uses get_account_summary tool to fetch your data]

User: "Create a new sales pipeline using GPT-4"
Claude: [Uses get_pipeline_options and create_pipeline tools]
```

## Testing the Connection

You can test the bridge manually:

```bash
# Set your token
export GENUDO_TOKEN="your_token_here"

# Run the bridge
node index.js

# Send a test message (paste this and press Enter):
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

# You should receive a response with server info
```

## Troubleshooting

### "GENUDO_TOKEN environment variable is required"
- Make sure you've set the token in your Claude Code config
- Verify the token is valid in your Genudo account

### "MCP handshake failed" / no response
- Check that `GENUDO_BASE_URL` is correct (defaults to `https://api.genudo.ai`) — the
  bridge POSTs to `<base>/mcp`
- Verify your server is running and accessible
- Check firewall/network settings

### "HTTP 401: Unauthorized"
- Your token is invalid or expired
- Generate a new token in your Genudo account settings

### Connection Issues with Self-Signed Certificates
- The bridge is configured to accept self-signed certificates for local development
- For production, use proper SSL certificates

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GENUDO_TOKEN` | **Yes** | - | Your Genudo token from account settings |
| `GENUDO_BASE_URL` | No | `https://api.genudo.ai` | Base URL for self-hosted Genudo instances |
| `GENUDO_ALLOW_INSECURE_SSL` | No | `false` | Allow self-signed SSL certificates (local development only) |
| `GENUDO_REQUEST_TIMEOUT` | No | `8000` | Per-attempt request timeout in ms before retrying |
| `GENUDO_REQUEST_RETRIES` | No | `4` | Number of attempts for a request before giving up |
| `GENUDO_WORKDIR` | No | current directory | Root the agent writes local pipeline mirrors, version snapshots and cached guides into |

## Development

### Project Structure
```
genudo-mcp-client/
├── index.js           # Main bridge script
├── package.json       # Node.js project config
├── .env.example       # Environment variables template
└── README.md          # This file
```

### How It Works

1. Bridge performs the MCP handshake against `<base>/mcp` (Streamable HTTP)
2. Reads JSON-RPC requests from stdin (from Claude Code)
3. Forwards each one as an HTTP POST to that same endpoint
4. Returns responses via stdout back to Claude Code

Since v2.5.0 there is no SSE step: Streamable HTTP is a single endpoint that takes
every message as a POST. If you don't need the bridge's local guide tools, prompts or
response slimming, you can skip it entirely and point your client at the server:
`claude mcp add --transport http genudo https://api.genudo.ai/mcp`

```
Claude Code → (stdin) → Bridge → (HTTPS) → Genudo MCP Server
                ↑                              ↓
                └─────── (stdout) ←────────────┘
```

## Security Notes

- **Never commit your token** to version control
- Store tokens securely (environment variables, secrets manager)
- Rotate tokens regularly
- Use HTTPS in production
- Limit token scopes to minimum required access

## Privacy Policy

This client is a local bridge. It does not collect, store, or transmit your data
anywhere except your confi