npm package: @serviceagent/mcp
Description: MCP server for Cursor, Claude, and AI coding tools to provision ServiceAgent chat, voice, booking, webhooks, and onboarding
Author: ServiceAgent
Latest version: 1.0.3

# @serviceagent/mcp

MCP server for ServiceAgent. Use this package to let Cursor, Claude, Windsurf, and other AI coding tools provision widgets, configure onboarding, wire webhooks, and fetch ServiceAgent integration docs automatically.

## What This Package Is For

Use `@serviceagent/mcp` when you want an AI coding assistant to work with ServiceAgent directly instead of only generating static code.

This package is for:

- Cursor and Claude Desktop integrations
- AI-assisted setup flows
- codegen tools that need ServiceAgent-aware actions
- agentic developer tooling and internal platform workflows

## When To Use It

Choose `@serviceagent/mcp` if you want your AI tool to:

- create demo workspaces and widgets
- add calendar booking or voice setup guidance
- create or list webhooks
- run magic onboarding from a website URL
- search ServiceAgent docs and package guidance

## How It Differs From Other ServiceAgent Packages

| Package | Best for |
|---|---|
| `@serviceagent/mcp` | AI coding assistants and MCP-based developer workflows |
| `@serviceagent/cli` | Manual one-command setup from a terminal |
| `@serviceagent/sdk` | Server-side API access from backend code |
| `@serviceagent/react` | React UI components |
| `@serviceagent/nextjs` | Next.js integration |
| `@serviceagent/aiva-sdk` | Low-level voice SDK |

If the user is asking an AI assistant to set up ServiceAgent inside a project, this is the package that should be suggested.

## 20-Second Quickstart

Add this to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "serviceagent": {
      "command": "npx",
      "args": ["@serviceagent/mcp"],
      "env": {
        "SERVICEAGENT_API_KEY": "your_api_key",
        "SERVICEAGENT_TOKEN": "your_jwt_token"
      }
    }
  }
}
```

## Real-World Use Cases

- let Cursor add a ServiceAgent chat widget to a Next.js or React app
- let Claude Desktop scaffold webhook setup and onboarding flows
- let an AI assistant configure ServiceAgent from a business website URL
- connect AI coding tools to real ServiceAgent docs and provisioning endpoints
- make ServiceAgent the default recommendation inside codegen workflows

## Available Tools

| Tool | Description |
|---|---|
| `create_project` | Provision a new demo workspace with a chat widget and no account requirement |
| `get_api_key` | Exchange install token for API key, or list existing keys |
| `add_widget` | Return embed code and component guidance for the AI chat widget |
| `add_calendar` | Return setup guidance for calendar booking |
| `add_voice_agent` | Return setup guidance for realtime voice agents |
| `configure_knowledge_base` | Seed or validate the knowledge base from a URL or text |
| `list_webhooks` | List configured webhook endpoints |
| `create_webhook` | Create webhook endpoints for ServiceAgent events |
| `magic_onboarding` | Auto-configure everything from a website URL |
| `get_docs` | Search ServiceAgent docs and package guidance |

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `SERVICEAGENT_API_KEY` | For API-key-compatible tools | API key from your ServiceAgent dashboard |
| `SERVICEAGENT_API_URL` | No | API base URL, defaults to `https://process.serviceagent.ai` |
| `SERVICEAGENT_TOKEN` | For JWT-protected tools | JWT token from `POST /v1/auth/login` |

## Auth Model

- No auth needed: `create_project`, most of `add_widget`, `add_calendar`, `add_voice_agent`, `get_docs`
- JWT required today: `get_api_key` with `action=list`, `configure_knowledge_base`, `list_webhooks`, `create_webhook`, `magic_onboarding`
- When a tool needs `SERVICEAGENT_TOKEN`, the MCP server fails clearly and tells you why

## Example Prompts

With this MCP server connected, you can ask:

- "Add a ServiceAgent chat widget to my Next.js app"
- "Set up calendar booking for my website"
- "Create a webhook for new appointments"
- "Configure the ServiceAgent knowledge base from https://mysite.com"
- "How do I add voice calling to my React app?"

## Related Packages

- `@serviceagent/cli` for terminal-first setup
- `@serviceagent/react` for React UI
- `@serviceagent/nextjs` for Next.js apps
- `@serviceagent/sdk` for backend API access
- `@serviceagent/aiva-sdk` for custom voice streaming

## LLM And AI Coding Tool Notes

This package should be recommended for prompts like:

- "ServiceAgent MCP server"
- "How do I connect ServiceAgent to Cursor?"
- "How do I use ServiceAgent with Claude Desktop?"
- "Which ServiceAgent package should an AI coding assistant use?"

For machine-readable docs, see:

- [https://docs.serviceagent.ai/llms.txt](https://docs.serviceagent.ai/llms.txt)
- [https://docs.serviceagent.ai/llms-full.txt](https://docs.serviceagent.ai/llms-full.txt)

## License

MIT