wati-astra-cli 0.2.0

Wati Astra CLI: agent optimizer and MCP server (Go binary wrapped for pip)

Astra Insight MCP

A standalone MCP server + interactive CLI that provides a self-contained agent optimization loop — read data, update instructions, run tests, evaluate, and iterate — all through the Astra Gateway public API.

v0.2.0 — 134 MCP tools, 140+ gateway API methods.

Install

pip install wati-astra-cli
astra version          # verify
astra auth             # configure keys (interactive)
astra                  # start interactive REPL
astra server           # run Streamable HTTP MCP server

Or build from source:

go install github.com/ClareAI/astra-insight-mcp/cmd/astra@latest

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                    astra-insight-mcp (this repo)                     │
│                                                                      │
│  Streamable HTTP MCP Server (spec 2025-03-26)                        │
│  POST /mcp  — JSON-RPC 2.0 (JSON or SSE response)                   │
│  GET  /mcp  — SSE notification stream                                │
│  DELETE /mcp — Terminate session                                     │
│  GET /healthz — Health check                                         │
│                                                                      │
│  134 tools across 15 categories                                      │
│  Agent / Chat / KB / Testing / Voice / Integrations / Analytics      │
└───────────────────────────┬──────────────────────────────────────────┘
                            │  HTTP (Bearer token)
                            ▼
                 Astra Gateway API
              astra-gateway.wati.io/v1

CLI Commands

astra                      Interactive REPL (default)
astra chat                 Same as above
astra server               Run Streamable HTTP MCP server
astra auth                 Configure LLM + Astra platform keys
astra auth clear           Remove all saved credentials
astra auth status          Show current auth configuration
astra auth --oauth         Browser OAuth PKCE login
astra version              Print version
astra help                 Show help

Supported API Endpoints (v0.2.0)

Agents (12 tools)

Tool	Method	Endpoint	Description
list_agents	GET	/v1/agents	List all agents with summaries
get_agent	GET	/v1/agents/{id}	Get agent details
create_agent	POST	/v1/agents	Create a new agent
update_agent	PUT	/v1/agents/{id}	Update agent fields
delete_agent	DELETE	/v1/agents/{id}	Delete an agent
publish_agent	POST	/v1/agents/{id}/publish	Publish draft to live
clone_agent	POST	/v1/agents/{id}/clone	Clone agent for experiments
update_agent_instruction	PUT	/v1/agents/{id}/instruction	Update draft instructions
get_runtime_config	GET	/v1/agents/{id}/runtime-config	Get live/draft runtime config
update_agent_attributes	PUT	/v1/agents/{id}/attributes	Update agent attributes
set_agent_enabled	PUT	/v1/agents/{id}/enabled	Enable/disable agent
export_contacts	GET	/v1/agents/{id}/contacts/export	Export agent contacts as CSV

Brandkit (6 tools)

Tool	Method	Endpoint	Description
get_brandkit	GET	/v1/agents/{id}/brandkit	Get brand kit
fetch_brandkit	POST	/v1/brandkit	Fetch brand from domain
create_brandkit	POST	/v1/agents/{id}/brandkit	Create brand kit
update_brandkit	PUT	/v1/agents/{id}/brandkit	Update brand kit
delete_brandkit	DELETE	/v1/agents/{id}/brandkit	Delete brand kit

Chat (4 tools)

Tool	Method	Endpoint	Description
send_test_message	POST	/v1/chat	Send message (supports streaming & multi-turn)
send_test_message (preview)	POST	/v1/chat-preview	Preview chat (no conversation saved)
send_test_message (test)	POST	/v1/chat-test	Test chat with evaluation
retrieve_knowledge	POST	/v1/knowledge/retrieve	Retrieve from knowledge base

Conversations (9 tools)

Tool	Method	Endpoint	Description
list_conversations	GET	/v1/conversations	List conversations with filters
get_conversation	GET	/v1/conversations/{id}	Get conversation details
get_conversation_messages	GET	/v1/conversations/{id}/messages	Get message history
get_conversation_contact	GET	/v1/conversations/{id}/contact	Get conversation contact
get_conversations_batch	GET	/v1/conversations/{id} x N	Batch fetch conversations
get_conversation_params	GET	/v1/conversations/{id}/params	Get conversation parameters
upsert_conversation_params	PUT	/v1/conversations/{id}/params	Upsert conversation parameters
delete_conversation_params	DELETE	/v1/conversations/{id}/params	Delete conversation parameters

Contacts (5 tools)

Tool	Method	Endpoint	Description
get_contacts_and_leads	GET	/v1/contacts	List contacts with filters
get_contact	GET	/v1/contacts/{id}	Get contact details
get_contact_conversations	GET	/v1/contacts/{id}/conversations	Contact's conversations
create_contact	POST	/v1/contacts	Create a contact
delete_contact	DELETE	/v1/contacts/{id}	Delete a contact

Knowledge Base (8 tools)

Tool	Method	Endpoint	Description
create_knowledge_base	POST	/v1/knowledge-bases	Create empty KB
list_knowledge_documents	GET	/v1/knowledge-bases/{id}/documents	List KB documents
create_knowledge_document	POST	/v1/knowledge-bases/{id}/documents	Create text document
delete_knowledge_document	DELETE	/v1/knowledge-bases/{id}/documents/{did}	Delete document
import_knowledge_from_url	POST	/v1/knowledge-bases/{id}/import/url	Import from URL
import_knowledge_from_website	POST	/v1/knowledge-bases/{id}/import/website	Crawl & import website
import_knowledge_from_file	POST	/v1/knowledge-bases/{id}/import/file	Upload file (PDF, etc.)
get_import_status	GET	/v1/knowledge-bases/{id}/import/status	Check import job status

Annotations (6 tools)

Tool	Method	Endpoint	Description
list_annotations	GET	/v1/agents/{id}/annotations	List FAQ annotations
create_annotation	POST	/v1/agents/{id}/annotations	Create FAQ annotation
get_annotation	GET	/v1/agents/{id}/annotations/{aid}	Get annotation details
update_annotation	PUT	/v1/agents/{id}/annotations/{aid}	Update annotation
delete_annotation	DELETE	/v1/agents/{id}/annotations/{aid}	Delete annotation
batch_delete_annotations	DELETE	/v1/agents/{id}/annotations/batch	Batch delete annotations

Integrations & MCP Actions (22 tools)

Tool	Method	Endpoint	Description
list_integration_templates	GET	/v1/mcp/action_templates	Available action templates
list_configured_integrations	GET	/v1/mcp/actions	All configured actions
get_configured_integration	GET	/v1/mcp/actions/{id}	Get action details
create_integration	POST	/v1/mcp/actions	Create an action
delete_integration	DELETE	/v1/mcp/actions/{id}	Delete an action
execute_integration_action	POST	/v1/mcp/actions/{id}/execute	Execute action
create_integration_auth	POST	/v1/mcp/auth	Initiate OAuth flow
get_integration_auth	GET	/v1/mcp/auth/{id}	Get auth connection
delete_integration_auth	DELETE	/v1/mcp/auth/{id}	Delete auth connection
wait_integration_auth	POST	/v1/mcp/auth/{id}/wait	Wait for OAuth callback
refresh_integration_auth	POST	/v1/mcp/auth/{id}/refresh	Refresh connection token
register_agent_integrations	POST	/v1/mcp/register	Register tools to agent
deregister_agent_integrations	POST	/v1/mcp/deregister	Remove tools from agent
list_agent_integrations	GET	/v1/mcp/agents/{id}/tools	List agent's registered tools
get_integration_platforms	GET	/v1/mcp/info	Available platforms
get_slack_channels	GET	/v1/mcp/platforms/slack/channels	Slack channels
get_wati_attributes	GET	/v1/mcp/platforms/wati/attributes	WATI attributes
get_wati_channels	GET	/v1/mcp/platforms/wati/channels	WATI channels
get_wati_templates	GET	/v1/mcp/platforms/wati/templates	WATI templates
get_hubspot_properties	GET	/v1/mcp/platforms/hubspot/properties	HubSpot properties
get_salesforce_fields	GET	/v1/mcp/platforms/salesforce/fields	Salesforce fields
get_google_sheets_spreadsheets	GET	/v1/mcp/platforms/google-sheets/spreadsheets	Google Sheets

Connections (4 tools)

Tool	Method	Endpoint	Description
list_connections	GET	/v1/connections	List platform connections
create_connection	POST	/v1/connections	Create connection mapping
get_connection	GET	/v1/connections/{id}	Get connection details
delete_connection	DELETE	/v1/connections/{id}	Delete connection

Analytics (2 tools)

Tool	Method	Endpoint	Description
get_analytics	GET	/v1/analytics	Conversation & lead analytics
get_lead_distribution	GET	/v1/distribution	Lead score distribution

Templates (3 tools)

Tool	Method	Endpoint	Description
list_templates	GET	/v1/templates	List agent templates
list_template_categories	GET	/v1/templates/categories	Template categories
get_template	GET	/v1/templates/{id}	Template details

Webhooks (4 tools)

Tool	Method	Endpoint	Description
list_webhooks	GET	/v1/webhooks	List webhooks
create_webhook	POST	/v1/webhooks	Create webhook
update_webhook	PUT	/v1/webhooks/{id}	Update webhook
delete_webhook	DELETE	/v1/webhooks/{id}	Delete webhook

Testing (24 tools)

Tool	Method	Endpoint	Description
start_test_pipeline	POST	/v1/testing/pipeline	Full pipeline: generate → execute → analyze
list_pipeline_jobs	GET	/v1/testing/pipeline/jobs	List pipeline jobs
get_pipeline_job	GET	/v1/testing/pipeline/jobs/{id}	Get pipeline status
create_test_suite	POST	/v1/testing/test-suites	Create/generate test suite
list_test_suites	GET	/v1/testing/test-suites	List test suites
get_test_suite	GET	/v1/testing/test-suites/{id}	Get suite with cases
get_test_suite_progress	GET	/v1/testing/test-suites/{id}/progress	Generation progress
add_test_case	POST	/v1/testing/test-suites/{id}/test-cases	Add test case
delete_test_case	DELETE	/v1/testing/test-cases/{id}	Delete test case
batch_delete_test_cases	DELETE	/v1/testing/test-cases/batch	Batch delete cases
create_test_run	POST	/v1/testing/test-suites/{id}/runs	Execute test suite
list_test_runs	GET	/v1/testing/runs	List runs
get_test_run	GET	/v1/testing/runs/{id}	Get run results
delete_test_run	DELETE	/v1/testing/runs/{id}	Delete run
list_runs_for_suite	GET	/v1/testing/test-suites/{id}/runs	Runs for a suite
create_run_analysis	POST	/v1/testing/runs/{id}/analyses	AI-powered analysis
get_run_analysis	GET	/v1/testing/runs/{id}/analyses	Get analysis
get_analysis	GET	/v1/testing/analyses/{id}	Get analysis by ID
analyze_failures	POST	/v1/testing/runs/{id}/analyze-failures	Diagnose failures
generate_instruction	POST	/v1/testing/generate-instruction	AI-generate improved instruction
get_agent_test_overview	GET	/v1/testing/agents/{id}/overview	Agent test summary
get_agent_latest_test_suite	GET	/v1/testing/agents/{id}/latest-suite	Latest suite
import_test_csv	POST	/v1/testing/agents/{id}/import-csv	Import test cases from CSV

Voice (25 tools)

Tool	Method	Endpoint	Description
list_voice_agents	GET	/v1/voice/agents	List voice agents
get_voice_agent	GET	/v1/voice/agents/{id}	Get voice agent
get_voice_agent_by_text_agent	GET	/v1/voice/agents/by-text-agent	Find by text agent
get_default_tenant_voice_agents	GET	/v1/voice/agents/default	Default tenant agents
create_voice_agent	POST	/v1/voice/agents	Create voice agent
quick_create_voice_agent	POST	/v1/voice/agents/quick-create	Quick create from template
update_voice_agent	PUT	/v1/voice/agents/{id}	Update voice agent config
delete_voice_agent	DELETE	/v1/voice/agents/{id}	Delete voice agent
publish_voice_agent	POST	/v1/voice/agents/publish	Publish voice agent
get_voice_agent_count	GET	/v1/voice/agents/count	Count voice agents
check_voice_agent_exists	HEAD	/v1/voice/agents/{id}	Check existence
new_voice_call	POST	/v1/voice/calls/new	Start voice call
web_new_voice_call	POST	/v1/voice/calls/web-new	WebRTC voice call
test_new_voice_call	POST	/v1/voice/calls/test-new	Test voice call
terminate_voice_call	POST	/v1/voice/calls/terminate	Terminate call
test_terminate_voice_call	POST	/v1/voice/calls/test-terminate	Terminate test call
initiate_outbound_call	POST	/v1/voice/calls/outbound/initiate	Initiate outbound call
get_webrtc_config	GET	/v1/voice/webrtc/config	WebRTC configuration
list_minimax_voices	GET	/v1/voice/minimax-voices	List Minimax voices
get_minimax_voice	GET	/v1/voice/minimax-voices/{id}	Get voice details
submit_voice_clone	POST	/v1/voice/minimax-voices/submit-clone	Start voice cloning
search_voice_library	GET	/v1/voice/minimax-voices/voice-library/search	Search voice library
update_minimax_voice	PUT	/v1/voice/minimax-voices/{id}	Update voice
search_collected_voices	GET	/v1/voice/minimax-voices/collected	Tenant's collected voices
upload_user_voice	POST	/v1/voice/minimax-voices/upload-user-voice	Upload audio for cloning

Utility (4 tools)

Tool	Method	Endpoint	Description
perplexity_search	POST	/v1/search	Web search via Perplexity
get_wati_settings	GET	/v1/settings/wati	WATI platform settings
list_skills	—	—	List available agent skills
activate_skill / deactivate_skill	—	—	Toggle skill context

Running Modes

1. PyPI Package (recommended)

pip install wati-astra-cli
astra                      # interactive REPL
astra server               # MCP server on :8080

2. Go Binary

go run ./cmd/astra         # interactive REPL
go run ./cmd/astra server  # MCP server
go run ./cmd/main.go       # legacy MCP server entry point

3. Docker

docker build -t astra-insight-mcp .
docker run -p 8080:8080 \
  -e ASTRA_GATEWAY_BASE_URL=https://astra-gateway.wati.io \
  -e ASTRA_API_KEY=sk_live_... \
  astra-insight-mcp

Authentication

Every tool call requires an auth token, resolved in this order:

Priority	Source	Example
1	api_key argument in tool call	"api_key": "sk_live_xxx"
2	ASTRA_API_KEY env var	export ASTRA_API_KEY=sk_live_xxx
3	ASTRA_ACCESS_TOKEN env var	export ASTRA_ACCESS_TOKEN=astra_at_xxx
4	ASTRA_OAUTH_ACCESS_TOKEN env var	export ASTRA_OAUTH_ACCESS_TOKEN=astra_at_xxx
5	~/.astra/oauth_token.json file	Written by astra auth --oauth

OAuth Login

astra auth --oauth --env dev     # browser OAuth (dev)
astra auth --oauth --env prod    # browser OAuth (prod)

Environment Variables

MCP Server

Variable	Default	Description
PORT	8080	Server port
ASTRA_GATEWAY_BASE_URL	https://astra-gateway.wati.io	Gateway API URL
ASTRA_API_KEY	—	API key (sk_live_*)
ASTRA_ACCESS_TOKEN	—	OAuth token
RATE_LIMIT_PER_MIN	60	Rate limit per IP

CLI Agent

Variable	Default	Description
LLM_API_KEY / OPENAI_API_KEY	—	LLM API key
LLM_BASE_URL	https://api.openai.com/v1	LLM endpoint
LLM_MODEL	anthropic/claude-sonnet-4	Model name

Quick Start

# Start MCP server
astra server

# List all tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# List agents
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{"name":"list_agents","arguments":{"api_key":"sk_live_xxx"}}
  }'

# Create an agent
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{"name":"create_agent","arguments":{
      "api_key":"sk_live_xxx",
      "name":"My Agent",
      "knowledge_base_id":"kb-uuid"
    }}
  }'

# Run full test pipeline
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":4,"method":"tools/call",
    "params":{"name":"start_test_pipeline","arguments":{
      "api_key":"sk_live_xxx","agent_id":"uuid","user_id":"tester"
    }}
  }'

Recipes

Pre-built optimization recipes are available at astra-docs.wati.io/recipes:

• Create Agent End-to-End — 5-step agent creation with brand kit, KB, annotations
• Setup Knowledge Base — KB creation with import strategies
• Optimize Agent Instructions — Analyze performance and improve instructions
• Setup Voice Agent — Voice agent creation and configuration
• Clone Voice — Voice cloning via Minimax TTS
• Connect Integration (OAuth) — OAuth flow for HubSpot, Slack, Salesforce, etc.
• Run Test Pipeline — Systematic testing with analysis
• Analyze Conversations — Conversation analysis and annotation
• Check Agent Performance — Performance metrics dashboard
• Debug API Errors — Common error diagnosis and fixes
• WATI MCP Auth — WATI platform auth troubleshooting
• Voice Operations — Voice agent operations quick reference

License

Proprietary — WATI / Clare.AI