Model Context Protocol (MCP)

PushGo now natively supports the Model Context Protocol (MCP). MCP is an open protocol that enables AI models (like Claude, ChatGPT, etc.) to securely access local or remote tools and data.

Authentication Modes

PushGo MCP server supports two primary modes of operation:

Feature	OAuth2 Mode (Recommended)	Legacy / Standard Mode
Security	High (Token-based, scoped grants)	Medium (Key-based or public)
Channel Password	NOT required in tool arguments	REQUIRED in every tool call
Setup Flow	One-time OAuth binding required	Direct access with gateway token
Best For	Production AI agents, secure sharing	Personal scripts, trusted environments

Core Features

The PushGo MCP server provides the following core capabilities:

1. Push Notification Tools (`mcp:tools`)

AI models can use the following tools for various push operations:

Message Sending

pushgo.message.send: Send a standard push message.
- Parameters: channel_id (Required), title (Required), body, url, images, severity, ttl, metadata, thing_id (Optional scope).
- Note: Passing password is forbidden in OAuth2 mode; it is required in Legacy mode.

Event Management (Event API)

pushgo.event.create: Create a new lifecycle event.
pushgo.event.update: Update an existing event’s status or information.
pushgo.event.close: Close an active event.
- Core Parameters: event_id (Required for update/close), status, message, severity, event_time, started_at, ended_at.

Entity Management (Thing API)

pushgo.thing.create: Create a persistent object in a channel.
pushgo.thing.update: Update object attributes.
pushgo.thing.archive: Archive an object.
pushgo.thing.delete: Permanently delete an object.
- Core Parameters: thing_id (Required), title, description, tags, external_ids, location_type, location_value.

2. Authorization & Channel Management (`mcp:channels:manage`)

Used to manage the binding relationship between the AI assistant and user channels:

pushgo.channel.list: List all channels currently authorized for the AI assistant.
pushgo.channel.unbind: Revoke the AI assistant’s access to a specific channel.
pushgo.channel.bind.start: Initiate a channel binding (or revocation) session.
- Parameters: action (“bind” or “revoke”), requested_channel_id (Optional suggestion).
- Returns: bind_url (User must open this in a browser to complete OAuth authorization).
pushgo.channel.bind.status: Poll the status of a binding session.
- Parameters: bind_session_id.

3. Resource Access (`mcp:channels:manage`)

AI models can read the following resources:

pushgo://channels: A list of all authorized channels.
pushgo://channels/{channel_id}: Detailed status and recent audit summaries for a specific channel.

How to Use

1. Enable MCP

In your self-hosted environment, set the following environment variables:

PUSHGO_MCP_ENABLED=true
PUSHGO_PUBLIC_BASE_URL=https://your-gateway.com

2. Configure in AI Clients

For example, in Claude Desktop, add the following to your configuration file:

{
  "mcpServers": {
    "pushgo": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/inspector", "https://your-gateway.com/mcp"]
    }
  }
}

(Note: PushGo uses HTTP SSE or JSON-RPC transport and supports standard OAuth2 authentication)

3. Authorization Flow

The AI assistant will first attempt to call pushgo.channel.bind.start.
it will provide an authorization URL (e.g., https://your-gateway.com/mcp/bind/session?...).
Open this URL in your browser and select the channel you wish to authorize for the AI.
Once authorized, the AI assistant can automatically send messages through that channel.

Scopes

MCP access is controlled by two primary scopes:

mcp:tools: Allows calling push tools.
mcp:channels:manage: Allows managing channel authorizations and reading resources.

Predefined Clients (Optional)

If you wish to avoid dynamic registration, you can specify clients at startup:

PUSHGO_MCP_PREDEFINED_CLIENTS="my_client_id:my_client_secret"