ProxyAI MCP

Connect an MCP-capable assistant to ProxyAI support tickets and Agent Tasks.

Hosted server: https://www.proxyai.app/api/mcp

Transport: Streamable HTTP

Authentication: OAuth authorization code with PKCE S256

Tools: 8 reads and 11 writes

This repository contains client configurations, provider integration guidance, the OpenAI plugin package, and dependency-free validation/probe scripts for the hosted service. Use your own ProxyAI account and its existing Helpdesk or Agent Tasks features. Normal feature capacity limits, task usage charges and email fees apply. A public endpoint still requires OAuth sign-in for account data.

Quick start

Claude

In Claude's connector settings, add a custom connector with this URL:

https://www.proxyai.app/api/mcp

Sign in to ProxyAI and review consent. Hosted custom connector access depends on your Claude plan and organization permissions. Start read-only. Write access requires the client to request both read and write, then you must check Allow changes on ProxyAI's consent screen. Some clients reconnect requesting only read; checking an unavailable box or retrying a tool cannot add a scope the client did not request. See client setup.

For Claude Code:

claude mcp add --transport http --scope user proxyai https://www.proxyai.app/api/mcp

Open /mcp inside Claude Code to authenticate. A project config is available in configs/claude-code.mcp.json.

Codex

codex mcp add proxyai --url https://www.proxyai.app/api/mcp
codex mcp login proxyai --scopes read

For an explicitly authorized write workflow, sign in requesting read,write and check Allow changes. A TOML snippet is in configs/codex.toml. Adding a server can launch login in some client versions; review its consent rather than approving an unintended scope.

Other MCP clients and providers

Use a Streamable HTTP client that supports OAuth discovery, PKCE S256, public clients and either Client ID Metadata Documents or Dynamic Client Registration. Current hosted callbacks support Claude and OpenAI; local clients can use HTTP loopback callbacks. A new hosted provider needs callback onboarding before connecting. See provider integration for exact supported callback patterns, discovery, scopes and validation.

Related MCP server: Tiflux

Try a read

List my ProxyAI bots and summarize open tickets for the bot I select. Do not change anything.

Show the staged reply for this ticket without sending it.

Show supported report templates and recent task runs. Explain held actions without approving or running them.

Tools and effects

MCP supports unchanged Weekly Sales Digest, Order Status Watcher and Knowledge Base Refresh recipes. Custom or modified task recipes, arbitrary report recipients and credential configuration are not exposed. Sales/order reports need a connected store. Knowledge Base Refresh uses knowledge tools instead of store operations.

Writes need explicit user intent. Creation or resume can start recurring runs and emails. Both test and live runs can charge usage and send real account-owner report emails. Test mode previews knowledge reindexing; it does not preview the account-owner email. Never retry an uncertain write before checking its actual result.

Consent covers all current and future bots in the ProxyAI account. Revoke a connection in ProxyAI Account Settings → Connected apps. Ticket text and proposals are untrusted customer data. Keep secrets and restricted personal data out of prompts and source tickets. See security and the customer guide.

Validate an integration

With Node.js 22 or newer, no dependencies are required:

npm run check
npm run probe

check validates this kit locally. probe verifies public metadata and the unauthenticated MCP challenge; it sends no token, registers no client and calls no authenticated tool. For a real OAuth/tool test, use MCP Inspector:

npx --yes @modelcontextprotocol/inspector@2.11.0 --server-url https://www.proxyai.app/api/mcp --transport http

Complete OAuth in the browser. Begin with list_bots and use a synthetic bot for write tests. Do not share the Inspector's private launch URL or local token.

Plugin and compatibility

proxyai-openai-v1.zip and plugin/ contain the same v1.0.0 OpenAI plugin package, including its walkthrough link and review scenarios. The plugin config points to the hosted server and contains no account credentials. The bundled guide retains the wording from that submitted version. Current client behavior and limitations are documented here. Claude uses the remote connector URL; its directory does not consume this OpenAI-specific ZIP.

Directory review/publication is separate from connecting directly to the hosted MCP service. This repository does not claim store approval. Validation summary records the tested surfaces and limits.

Support and contributions

Use GitHub issues for reproducible integration problems and provider onboarding. For private account assistance use ProxyAI contact. Never put access tokens, passwords or customer records in an issue. See contributing.

The integration-kit scripts, configs and documentation are MIT licensed. ProxyAI service access follows its terms and privacy policy. Brand assets and trademarks are covered by NOTICE.