Standard A2A-compatible multi-project service wrapping Cursor CLI agent command
npm install cursor-agent-a2a

Independent A2A-compatible service wrapping Cursor CLI agent command. This service provides a standard A2A (Agent-to-Agent) protocol interface for Cursor CLI, allowing it to be called from other A2A-compatible services like AgentStudio.
- ✅ A2A Protocol Compliant - Full support for A2A protocol endpoints
- ✅ Multi-turn Conversations - Session management with workspace persistence
- ✅ Streaming Responses - Server-Sent Events (SSE) for real-time updates
- ✅ Async Task Management - Long-running task support with status polling
- ✅ Workspace Management - Automatic workspace handling in multi-turn conversations
- ✅ Session Persistence - Workspace is automatically retrieved from session context
- ✅ Project ID Mapping - Map short project IDs to workspace paths for easier API calls
- ✅ Web Management UI - Manage project mappings through a user-friendly web interface
``bashClone the repository
git clone https://github.com/jeffkit/cursor-agent-a2a.git
cd cursor-agent-a2a
$3
`bash
Global installation (recommended for CLI usage)
npm install -g cursor-agent-a2a
or
pnpm add -g cursor-agent-a2aLocal installation
npm install cursor-agent-a2a
or
pnpm add cursor-agent-a2a
`$3
After global installation, you can use the
cursor-agent-a2a command:`bash
Install as system service
cursor-agent-a2a install --port 4300 --api-key your-api-keyManage service
cursor-agent-a2a start # Start the service
cursor-agent-a2a stop # Stop the service
cursor-agent-a2a restart # Restart the service
cursor-agent-a2a status # Check service statusView logs
cursor-agent-a2a logs # View last 50 lines
cursor-agent-a2a logs --follow # Follow logs (like tail -f)
cursor-agent-a2a logs --lines 100 # View last 100 lines
cursor-agent-a2a logs --type stderr # View only stderrUpgrade
cursor-agent-a2a upgrade # Upgrade to latest versionUninstall
cursor-agent-a2a uninstall # Remove system service
`Prerequisites
$3
Make sure Cursor CLI is installed and authenticated:
`bash
Install Cursor CLI
curl https://cursor.com/install -fsS | bashLogin (or set CURSOR_API_KEY environment variable)
cursor agent loginVerify authentication
cursor agent status
`Configuration
Set environment variables:
`bash
API Key for A2A authentication (default: cursor-agent-demo-key)
export CURSOR_AGENT_API_KEY=your-secure-api-keyServer port (default: 4937)
export PORT=4937Server host (default: 0.0.0.0)
export HOST=0.0.0.0Cursor API Key (optional, uses local login if not set)
export CURSOR_API_KEY=sk_your_cursor_api_keyDefault model (optional, defaults to sonnet-4.5)
export CURSOR_DEFAULT_MODEL=sonnet-4.5
`Running
$3
`bash
pnpm run dev
`$3
`bash
Build
pnpm run buildStart
pnpm start
`The service will start on
http://localhost:4937 (or your configured port).API Endpoints
All endpoints require API key authentication via
Authorization: Bearer header.$3
Get the agent's capabilities and metadata.
`bash
GET /.well-known/agent-card.json
Authorization: Bearer
`Response:
`json
{
"name": "Cursor Agent",
"description": "AI-powered code assistant via Cursor CLI...",
"version": "1.0.0",
"url": "http://localhost:4937",
"skills": [...],
"securitySchemes": [...]
}
`$3
Send a message and get an immediate response.
`bash
POST /messages
Authorization: Bearer
Content-Type: application/json{
"message": "Say hello",
"context": {
"workspace": "/path/to/project"
},
"sessionId": "optional-session-id"
}
`Response:
`json
{
"response": "Hello! I'm Claude, an AI programming assistant...",
"sessionId": "chat-12345",
"metadata": {
"processingTimeMs": 1234
}
}
`Streaming Mode:
Add
?stream=true or Accept: text/event-stream header:`bash
POST /messages?stream=true
Authorization: Bearer
Accept: text/event-stream
`$3
Create a long-running task and poll for status.
`bash
POST /tasks
Authorization: Bearer
Content-Type: application/json{
"message": "Long running task",
"context": {
"workspace": "/path/to/project"
},
"timeout": 600000,
"sessionId": "optional-session-id"
}
`Response:
`json
{
"taskId": "task-uuid",
"status": "pending",
"checkUrl": "/tasks/task-uuid"
}
`$3
`bash
GET /tasks/:taskId
Authorization: Bearer
`Response:
`json
{
"taskId": "task-uuid",
"status": "completed",
"output": {
"result": "Task completed successfully"
},
"createdAt": "2026-01-24T...",
"completedAt": "2026-01-24T..."
}
`$3
`bash
DELETE /tasks/:taskId
Authorization: Bearer
`Multi-turn Conversations
The service supports multi-turn conversations with automatic workspace management:
1. First message - Provide
workspace in context:
`json
{
"message": "Create a hello.js file",
"context": {
"workspace": "/path/to/project"
}
}
`
Response includes sessionId.2. Subsequent messages - Only need
sessionId, workspace is automatically retrieved:
`json
{
"message": "Modify the file to add a function",
"sessionId": "chat-12345"
}
`Project ID Mapping
The service supports mapping short project IDs to workspace paths for easier API calls.
$3
Access the web management interface at:
`
http://localhost:4937/manage
`Features:
- Add new project mappings
- Edit existing projects
- Delete project mappings
- Copy project IDs for API use
$3
Once you've created a project mapping, you can use the project ID in API calls:
`bash
Using project ID in URL (no need to specify workspace in context)
curl -X POST "http://localhost:4937/messages/:projectId" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"message": "Say hello"}'Traditional way (still supported)
curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Say hello",
"context": {
"workspace": "/path/to/project"
}
}'
`$3
When multiple workspace sources are provided, the resolution priority is:
1. Project ID from URL parameter (
:projectId)
2. Workspace from context.workspace
3. Workspace from session (if sessionId is provided)
4. Current working directory (fallback)$3
`bash
List all projects
GET /projectsGet specific project
GET /projects/:projectIdCreate new project
POST /projects
{
"name": "My Project",
"workspace": "/path/to/project"
}Update project
PUT /projects/:projectId
{
"name": "Updated Name",
"workspace": "/new/path"
}Delete project
DELETE /projects/:projectId
`All project management endpoints require API key authentication.
Model Configuration
You can configure which Cursor model to use in three ways:
$3
Specify the model in each API request:
`bash
curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Say hello",
"model": "sonnet-4.5",
"context": {"workspace": "/path/to/project"}
}'
`$3
Set a default model for all requests:
`bash
export CURSOR_DEFAULT_MODEL=sonnet-4.5
`$3
If neither is specified, the service defaults to
sonnet-4.5 (Claude 4.5 Sonnet).$3
To see all available models:
`bash
cursor agent --list-models
`Common models:
-
sonnet-4.5 - Claude 4.5 Sonnet (default, balanced performance)
- sonnet-4.5-thinking - Claude 4.5 Sonnet with extended thinking
- opus-4.5 - Claude 4.5 Opus (most capable, requires credits)
- opus-4.5-thinking - Claude 4.5 Opus with extended thinking
- gpt-5.2 - GPT-5.2
- gpt-5.2-codex - GPT-5.2 Codex (code-optimized)
- gemini-3-pro - Google Gemini 3 Pro
- gemini-3-flash - Google Gemini 3 Flash (fast)$3
1. Request body
model parameter (highest priority)
2. CURSOR_DEFAULT_MODEL environment variable
3. System default: sonnet-4.5 (fallback)$3
Using Sonnet (recommended for general use):
`bash
curl -X POST "http://localhost:4937/messages/project-id" \
-H "Authorization: Bearer cursor-agent-demo-key" \
-H "Content-Type: application/json" \
-d '{"message": "Say hello", "model": "sonnet-4.5"}'
`Using GPT-5.2 Codex:
`bash
curl -X POST "http://localhost:4937/messages/project-id" \
-H "Authorization: Bearer cursor-agent-demo-key" \
-H "Content-Type: application/json" \
-d '{"message": "Refactor this code", "model": "gpt-5.2-codex"}'
`Using environment default:
`bash
export CURSOR_DEFAULT_MODEL=gpt-5.2
pnpm run dev
All requests will use gpt-5.2 unless overridden
`Usage Examples
$3
Add to your project's
a2a-config.json:`json
{
"allowedAgents": [
{
"name": "Cursor Agent",
"url": "http://localhost:4937",
"apiKey": "your-api-key",
"description": "Cursor CLI agent via A2A",
"enabled": true
}
]
}
`Then use it in AgentStudio agents via the A2A client tool.
$3
`bash
Get agent card
curl -X GET "http://localhost:4937/.well-known/agent-card.json" \
-H "Authorization: Bearer your-api-key"Send message
curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Say hello",
"context": {
"workspace": "/path/to/project"
}
}'Continue conversation
curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Continue",
"sessionId": "chat-12345"
}'
`Development
`bash
Type checking
pnpm run type-checkBuild
pnpm run buildDevelopment with hot reload
pnpm run dev
``MIT
jeffkit (bbmyth@gmail.com)
Contributions are welcome! Please feel free to submit a Pull Request.