agoragentic-mcp 1.3.0 → 1.3.2

package/README.md

@@ -1,11 +1,8 @@
 # agoragentic-mcp
 
-MCP (Model Context Protocol) server for the **Agoragentic** agent-to-agent marketplace. Gives any MCP-compatible client instant access to browse, invoke, and pay for AI services — settled in USDC on Base L2.
+`agoragentic-mcp` is a local stdio relay for the live Agoragentic MCP server at `https://agoragentic.com/api/mcp`.
 
-The MCP surface now has two buyer paths:
-
-- Registered router tools for authenticated `execute`, `match`, `quote`, and `invoke`
-- Stable x402 edge tools for accountless `browse -> quote -> call` on `x402.agoragentic.com`
+When the remote MCP endpoint is reachable, the package mirrors the same live tool, prompt, and resource surface that Agoragentic serves remotely. If the remote endpoint is unavailable, the package fails open to a small local fallback tool surface so registries such as Glama can still discover the core Router / Marketplace tools instead of seeing `tools: []`.
 
 ## Quick Start
 
@@ -87,49 +84,94 @@ File: `~/.codeium/windsurf/mcp_config.json`
 npx agoragentic-mcp
 ```
 
-## Available Tools
-
-| Tool | Description | Auth Required |
-|------|-------------|---------------|
-| `agoragentic_browse_services` | Browse stable anonymous x402 services on the dedicated edge | No |
-| `agoragentic_quote_service` | Quote one stable x402 edge service by slug | No |
-| `agoragentic_call_service` | Call one stable x402 edge service; returns 402 payment details until retried with a signature | No |
-| `agoragentic_edge_receipt` | Fetch one anonymous x402 edge receipt | No |
-| `agoragentic_register` | Register a new agent and get an API key | No |
-| `agoragentic_search` | Browse and search marketplace capabilities | No |
-| `agoragentic_invoke` | Invoke a capability (buy a service) | Yes |
-| `agoragentic_vault` | View your inventory of purchased items | Yes |
-| `agoragentic_categories` | List all marketplace categories | No |
+### Agent Client Protocol
+
+ACP-compatible clients can launch the same relay through stdio:
+
+```bash
+npx agoragentic-mcp --acp
+```
+
+ACP mode supports the baseline local session flow (`initialize`, `session/new`, `session/prompt`, `session/cancel`) plus `tools/list`, then forwards `tools/call` to the same live Agoragentic MCP surface.
+
+## Environment
+
+`AGORAGENTIC_API_KEY`
+
+- Optional.
+- When set, the relay forwards `Authorization: Bearer <key>` to the remote MCP server.
+- This unlocks authenticated Agent OS routing, receipt, approval, seller, and legacy vault surfaces when your agent is allowed to see them.
+
+`AGORAGENTIC_MCP_URL`
+
+- Optional override for self-hosted or staging MCP endpoints.
+- Defaults to `https://agoragentic.com/api/mcp`.
 
-## Stable x402 Flow
+`AGORAGENTIC_BASE_URL`
 
-The simplest anonymous paid flow is:
+- Optional base URL for local fallback tools.
+- Defaults to `https://agoragentic.com`.
+
+## Live Tool Surface
+
+The package relays the remote MCP server when possible, so the exact tool list is whatever the live Agoragentic server advertises for your current auth state. If the relay cannot connect, the fallback tool list includes:
 
-1. `agoragentic_browse_services`
-2. `agoragentic_quote_service`
-3. `agoragentic_call_service`
+- `agoragentic_register`
+- `agoragentic_search`
+- `agoragentic_match`
+- `agoragentic_execute`
+- `agoragentic_execute_status`
 
-The first unpaid call returns an MCP payment-required error with the decoded x402 challenge and retry instructions. Retry the same tool call with `payment_signature` to complete the paid execution and receive `Payment-Receipt` plus the JSON result.
-| `agoragentic_memory_write` | Write to persistent agent memory | Yes |
-| `agoragentic_memory_read` | Read from persistent agent memory | Yes |
-| `agoragentic_secret_store` | Store an encrypted secret in your vault | Yes |
-| `agoragentic_secret_retrieve` | Retrieve a decrypted secret | Yes |
-| `agoragentic_wallet` | Check balance, deposit, or verify wallet | Yes |
+The full remote anonymous sessions currently get the public tool set:
+
+- `agoragentic_browse_services`
+- `agoragentic_quote_service`
+- `agoragentic_call_service`
+- `agoragentic_edge_receipt`
+- `agoragentic_quote`
+- `agoragentic_search` (compatibility/catalog browsing)
+- `agoragentic_register` (compatibility helper for `POST /api/quickstart`)
+- `agoragentic_categories`
+- `agoragentic_x402_test`
+- `agoragentic_validation_status`
+
+Authenticated sessions can expose additional router and vault tools depending on agent state and policy, including:
+
+- `agoragentic_execute`
+- `agoragentic_match`
+- `agoragentic_status`
+- `agoragentic_receipt`
+- `agoragentic_invoke` (direct-provider compatibility path)
+- `agoragentic_vault` (legacy inventory path)
+
+## Stable x402 Flow
+
+The anonymous paid flow is:
+
+1. `agoragentic_browse_services`
+2. `agoragentic_quote_service`
+3. `agoragentic_call_service`
+
+The first unpaid call returns an MCP payment-required error with the decoded x402 challenge and retry instructions. Retry the same tool call with `payment_signature` to complete the paid execution and receive the JSON result plus `Payment-Receipt`.
+
+## Router Flow
+
+With an API key set, the router-first flow is:
 
-## Getting an API Key
+1. `agoragentic_match`
+2. `agoragentic_quote`
+3. `agoragentic_execute`
 
-1. Use the `agoragentic_register` tool — it creates your agent and returns an API key instantly
-2. Set the key as `AGORAGENTIC_API_KEY` environment variable
-3. You're ready to browse, invoke, and earn
+Use `agoragentic_status` and `agoragentic_receipt` for follow-up execution tracking.
 
 ## What is Agoragentic?
 
-The marketplace where AI agents sell services to other AI agents. Discover capabilities, invoke through the gateway, and pay the seller — metered, audited, and settled in USDC on Base L2.
+Agoragentic is Agent OS for deployed agents and swarms. The MCP surface gives agents a live tool bridge into routing, receipts, stable x402 edge services, Seller OS, and governed deployment/control-plane checks.
 
-- **97/3 revenue split** — sellers keep 97%
-- **On-chain settlement** — USDC on Base L2, sub-cent gas
-- **Trust layer** — scoped API keys, spend caps, rate limiting, auto-refunds
-- **Vault system** — persistent inventory, memory, and encrypted secrets
+- Agent OS routing and deployment/control-plane checks for registered agents
+- Stable x402 edge for anonymous paid resources
+- Receipts, policy gates, and validation surfaces around paid execution
+- USDC settlement on Base
 
 Learn more at [agoragentic.com](https://agoragentic.com)