Update to current Orbit API and bundle Orbit's MCP server

.codex-plugin/plugin.json

@@ -1,8 +1,9 @@
 {
   "name": "orbit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
   "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
   "author": "Postman DevRel",
   "homepage": "https://github.com/Postman-Devrel/orbit-codex-plugin",
   "repository": "https://github.com/Postman-Devrel/orbit-codex-plugin",

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "orbit": {
+      "type": "streamable-http",
+      "url": "https://mcp.buildwithorbit.ai/mcp"
+    }
+  }
+}

README.md

@@ -20,6 +20,19 @@ This lets agents make informed decisions about which APIs to integrate without r
 codex plugin add Postman-Devrel/orbit-codex-plugin
 ```
 
+The plugin bundles Orbit's MCP server, so there is nothing else to configure -- no API
+key, no `codex mcp add`, no edits to `~/.codex/config.toml`. Installing the plugin
+registers the `search` and `integrate` tools, and the skill drives them.
+
+Requires a Codex version that supports plugin-bundled MCP servers over streamable HTTP.
+If your Codex only picks up stdio servers, add the server manually instead:
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.orbit]
+url = "https://mcp.buildwithorbit.ai/mcp"
+```
+
 ## Usage
 
 Run the `discover` skill with a capability query:
@@ -37,19 +50,31 @@ Search for multiple capabilities at once:
 ### Example output
 
 ```
-### Results for: "payment processing"
+### Results for: "Stripe create subscription"
 
-**Stripe - Create Subscription**
+**Create a subscription** (Stripe / Stripe Billing)
 - Method: `POST`
 - URL: `https://api.stripe.com/v1/subscriptions`
-- Description: Creates a new subscription on an existing customer.
-- **Evaluate Guide:** Use for: recurring billing, subscription lifecycle management,
-  plan upgrades/downgrades. Not supported: one-time payments (use Payment Intents),
-  physical goods shipping, tax calculation (use Stripe Tax).
+- Description: Creates a new subscription on an existing customer. Each customer can
+  have up to 500 active or scheduled subscriptions.
+- **Evaluate Guide:** Creates a recurring subscription for an existing customer and
+  determines how its initial invoice and payment are handled.
+  Use for: start recurring billing, configure initial payment behavior, create
+  scheduled subscriptions
+  Not supported: customer creation, one-time charges, changing existing subscription
+  items
 ```
 
+Note the query includes the provider name. A generic `"payment processing"` search
+returns Adyen, Moneris, and Peach Payments -- not Stripe. Naming the provider is the
+single biggest lever on result quality.
+
 Results are automatically saved to the `orbit-output/` directory as markdown files for later reference.
 
+Once you have chosen endpoints, the skill can also produce a **task brief** -- the auth
+requirements, base URLs, ordered request steps, and gotchas needed to write the
+integration.
+
 ## Design process
 
 Orbit works best when you use it at the start of a project to build an API blueprint before writing code. Here's the workflow:
@@ -62,27 +87,46 @@ Orbit works best when you use it at the start of a project to build an API bluep
 
 4. **Iterate.** Use those gaps as your next round of queries. "Find me APIs that handle payment refunds" or "I need an auth provider that supports token refresh." Each round narrows the design.
 
-5. **Save the blueprint.** The agent saves results to `orbit-output/` as a structured file you can reference throughout the project. This becomes your API design document, readable by both humans and agents.
+5. **Get the task brief.** Once the endpoint set is settled, the agent sends the selected endpoints plus your task to Orbit's `integrate` tool and gets back a brief covering auth, base URLs, and the request sequence -- the implementation plan, before you write code.
+
+6. **Save the blueprint.** The agent saves results to `orbit-output/` as a structured file you can reference throughout the project. This becomes your API design document, readable by both humans and agents.
 
 The goal is to make API selection decisions intentionally at design time, not discover limitations mid-sprint after you've already integrated half the stack.
 
-## The Orbit API
+## How it works
 
-The plugin calls a single endpoint:
+The plugin is a thin workflow layer over Orbit's MCP server:
 
-```
-POST https://fabric-gateway.postmanlabs.com/api/search
-Content-Type: application/json
+| | Provided by |
+|---|---|
+| `search` / `integrate` tools, request + response schemas | Orbit's MCP server (bundled) |
+| Capability decomposition, gap analysis, iteration, saved blueprint | This plugin's skill |
 
-{"q": "your search query"}
-```
+Keeping the API contract on the server side means Orbit can change its parameters
+without breaking installed copies of the plugin.
+
+### The underlying API
+
+No authentication is required. The MCP tools map one-to-one onto two REST endpoints on
+`https://api.buildwithorbit.ai`:
+
+| MCP tool | REST equivalent |
+|---|---|
+| `search` | `POST /v1/search` |
+| `integrate` | `POST /v1/integrate` |
 
-No authentication required. The response includes:
+`search` takes `q` (max 512 chars) plus optional `limit` (default 10, max 25) and
+`cursor`, and returns `data[]` entries with `id`, `resourceType`, `name`,
+`description`, `method`, `url`, and `evaluateGuide`, alongside `meta` carrying `q`,
+`total`, and `nextCursor`. `integrate` takes a `task` and 1-10 `resources` and returns
+a `taskBrief`.
 
-- `data[]` - Array of API endpoints with `id`, `name`, `description`, `method`, `url`, and `evaluateGuide`
-- `meta` - Search metadata with `q`, `total`, and `nextCursor`
+If the MCP server is ever unreachable, the skill falls back to these REST endpoints,
+documented in [references/orbit-api.md](skills/discover/references/orbit-api.md).
 
 ## Links
 
+- [Orbit documentation](https://www.buildwithorbit.ai/)
+- [Orbit API reference](https://www.buildwithorbit.ai/api-reference)
 - [Postman API Network](https://www.postman.com/explore)
 - [Postman](https://www.postman.com)

skills/discover/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: discover
-description: Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do.
+description: Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do, and can generate an integration task brief for the ones you pick.
 ---
 
 # Orbit API Discovery
 
 You are an API discovery agent. You help developers find the right APIs for their project by querying **Postman Orbit**, an agent-friendly search API built on top of the Postman API Network.
 
+This plugin bundles Orbit's MCP server, so its tools are available with no setup and no authentication.
+
 ## When to use
 
 Use this skill when a developer wants to:
 - Find APIs for a specific capability (e.g., "payment processing", "email sending", "geocoding")
 - Compare multiple APIs that serve the same purpose
 - Understand what an API can and cannot do before integrating it
 - Discover APIs for multiple capabilities in a single session
+- Get a concrete integration plan for APIs they have already chosen
 
 ## Input
 
@@ -24,17 +27,29 @@ The user provides one or more capability queries as natural language. Examples:
 
 Parse the user's message to extract individual capability queries. If the user lists multiple capabilities, run a separate search for each one.
 
+## Tools
+
+The bundled `orbit` MCP server provides two tools:
+
+- **`search`** — find and evaluate public API endpoints
+- **`integrate`** — turn chosen endpoints into an integration task brief
+
+Prefer these tools. If they are unavailable in the current session, read `references/orbit-api.md` and call the equivalent REST endpoints with curl; the request and response shapes are identical.
+
 ## How to search
 
-For each capability query, use Bash to call the Orbit API:
+Call the `search` tool once per capability query:
+
+- `q` — the query (required, max 512 characters)
+- `limit` — results per page (optional, default 10, max 25)
+- `clientName` — pass `"codex/orbit-plugin"` for anonymous usage analytics
 
-```
-curl -s -X POST https://fabric-gateway.postmanlabs.com/api/search \
-  -H "Content-Type: application/json" \
-  -d '{"q": "QUERY_HERE"}'
-```
+Query style materially affects result quality:
 
-Replace `QUERY_HERE` with the capability query. Keep queries concise and descriptive.
+- Include the product or provider name alongside the endpoint detail — `"PayPal create invoice"`.
+- Natural language works too — `"PayPal API to create an invoice"`.
+- Do **not** cram unrelated keywords into one query — `"paypal invoice payment delivery ordering"` returns worse results.
+- Do **not** use `OR`-separated queries. Run a separate `search` call per intent instead.
 
 ## How to format results
 
@@ -44,7 +59,7 @@ For each query, present results in this format:
 
 For each result in the `data` array, show:
 
-**{name}**
+**{name}** ({provider})
 - Method: `{method}`
 - URL: `{url}`
 - Description: {description}
@@ -57,7 +72,20 @@ The `evaluateGuide` field is the most valuable part of the response. It tells ag
 
 Always highlight the evaluateGuide content prominently. This is what differentiates Orbit from a standard API directory.
 
-If the `meta.total` count exceeds the number of returned results, mention that more results are available.
+Keep each result's `id` and `resourceType` on hand — the `integrate` tool needs them. Preserve `id` values verbatim; never parse, edit, or construct one.
+
+If `meta.total` exceeds the number of returned results, mention that more results are available. If `meta.nextCursor` is present, more pages exist — pass that value as `cursor` on a follow-up `search` call, but do not paginate automatically unless the user asks. Note that `nextCursor` is *absent* on the last page rather than null, and pagination stops at 40 results per query.
+
+## How to integrate
+
+When the user has a concrete task and has settled on endpoints, call the `integrate` tool:
+
+- `task` — what they are building (required, max 512 characters)
+- `resources` — entries of `{id, type}`, where `id` is a search result's `id` and `type` is that result's `resourceType`
+
+The schema allows up to 10 resources, but **keep calls narrow — 2 or 3 related endpoints**. Wide calls have been observed to return a one-line restatement instead of a real brief. To cover more endpoints, make several focused calls grouped by sub-task rather than one wide call.
+
+The response contains a `taskBrief` covering authentication requirements, base URLs, ordered request steps, parameters, expected responses, dependencies between steps, and other considerations. Present the brief and save it alongside the search results.
 
 ## Saving results
 
@@ -72,6 +100,7 @@ Filename pattern: `orbit-output/{slug}.md`
 Examples:
 - Single query "payment processing" -> `orbit-output/payment-processing.md`
 - Multiple queries "send emails" + "geocoding" -> `orbit-output/send-emails--geocoding.md`
+- A task brief -> `orbit-output/{task-slug}-brief.md`
 
 The saved file should contain:
 - A top-level heading with the date and queries
@@ -80,7 +109,8 @@ The saved file should contain:
 ## Guidelines
 
 - If no results are found for a query, say so clearly and suggest rephrasing.
-- Do not fabricate API results. Only show what the Orbit API returns.
+- Do not fabricate API results. Only show what Orbit returns.
 - When the user asks for multiple capabilities, run all searches and present results grouped by capability.
+- Lead your summary with the "Not supported" lines — those are the design gaps worth acting on before any code is written.
 - Keep your commentary brief. Let the API results speak for themselves.
-- If the response includes a `nextCursor` in `meta`, mention that more results are available but do not automatically paginate.
+- Both tools are read-only and safe to retry. On a rate-limit error, back off and retry.