diff --git a/docs/docs.json b/docs/docs.json index a02fc59d..04fd5807 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -75,7 +75,7 @@ }, { - "group": "Config", + "group": "Project Config", "pages": [ "publishing/config/index", "publishing/config/auth", diff --git a/docs/media/example-usage.png b/docs/media/example-usage.png new file mode 100644 index 00000000..a788b7ec Binary files /dev/null and b/docs/media/example-usage.png differ diff --git a/docs/publishing/config/auth.mdx b/docs/publishing/config/auth.mdx index e5d023a5..02a29d42 100644 --- a/docs/publishing/config/auth.mdx +++ b/docs/publishing/config/auth.mdx @@ -1,6 +1,6 @@ --- title: Auth -description: Configure auth for your product. +description: Configure auth for your project. --- Ship to production fast with Agentic's free, hosted authentication. Email & password, OAuth, GitHub, Google, Twitter, etc – if your origin API requires OAuth credentials, Agentic likely already supports it, and if not, [please let us know](/contact). @@ -12,9 +12,9 @@ Currently, Agentic supports the following auth providers: ## How it works -Your product's users will sign into Agentic, subscribe to your product using Stripe, and then be given an API key to use with their tool calls. +Your project's users will sign into Agentic, subscribe to your project using Stripe, and then be given an API key to use with their tool calls. -Agentic's MCP gateway will then track all usage of your product based on API keys. +Agentic's MCP gateway will then track all usage of your project based on API keys. See [Origin Metadata](/publishing/origin-metadata) for details on how Agentic's MCP gateway passes customer auth and subscription information to your origin server. diff --git a/docs/publishing/config/caching.mdx b/docs/publishing/config/caching.mdx index ed1da4bf..724f2158 100644 --- a/docs/publishing/config/caching.mdx +++ b/docs/publishing/config/caching.mdx @@ -1,6 +1,6 @@ --- title: Caching -description: Configure caching for your product's tools. +description: Configure caching for your project's tools. --- Opt-in to caching with familiar _cache-control_ and _stale-while-revalidate_ options. MCP tool calls include caching information in their _\_meta_ fields, providing parity with standard HTTP headers. diff --git a/docs/publishing/config/index.mdx b/docs/publishing/config/index.mdx index c53200d0..e790456b 100644 --- a/docs/publishing/config/index.mdx +++ b/docs/publishing/config/index.mdx @@ -1,6 +1,6 @@ --- title: Config Overview -description: Configuring your Agentic product. +description: Configuring your Agentic project. --- Every Agentic project needs a config file (`agentic.config.ts`, `agentic.config.js`, or `agentic.config.json`) to define the project's metadata, pricing, rate-limits, and any tool-specific behavior overrides. diff --git a/docs/publishing/config/rate-limits.mdx b/docs/publishing/config/rate-limits.mdx index b5f997ac..16e9a530 100644 --- a/docs/publishing/config/rate-limits.mdx +++ b/docs/publishing/config/rate-limits.mdx @@ -1,6 +1,6 @@ --- title: Rate Limits -description: Configure rate-limits for your product. +description: Configure rate-limits for your project. --- Agentic's durable rate-limiting is built on top of Cloudflare's global infrastructure. Customize the default rate-limits, change them based on a customer's pricing plan, or create custom tool-specific overrides. @@ -47,8 +47,7 @@ The default platform rate limit for `requests` is a limit of 1000 requests per m { enabled: true, interval: '1m', - limit: 1000, - mode: 'approximate' + limit: 1000 } ``` diff --git a/docs/publishing/config/tool-config.mdx b/docs/publishing/config/tool-config.mdx index 0f73914d..214ff14e 100644 --- a/docs/publishing/config/tool-config.mdx +++ b/docs/publishing/config/tool-config.mdx @@ -1,6 +1,6 @@ --- title: Tool Config -description: Configure tool-specific settings for your product. +description: Configure tool-specific settings for your project. --- `toolConfigs` is an optional array of tool configs which may be used to override the default gateway behavior for specific tools. diff --git a/docs/publishing/guides/existing-mcp-server.mdx b/docs/publishing/guides/existing-mcp-server.mdx index 597d119f..4e5d3b1a 100644 --- a/docs/publishing/guides/existing-mcp-server.mdx +++ b/docs/publishing/guides/existing-mcp-server.mdx @@ -1,6 +1,353 @@ --- title: Existing MCP Server -description: This guide shows how to publish an existing MCP server to Agentic's MCP Gateway. +description: This guide shows how to publish an existing MCP server to Agentic. --- -**TODO** + + **Prerequisite**: Please install [Node.js](https://nodejs.org) before + proceeding. + + +## 1. Install the Agentic CLI + + + +```bash npm +npm i -g @agentic/platform-cli +``` + +```bash pnpm +pnpm i -g @agentic/platform-cli +``` + +```bash bun +bun install -g @agentic/platform-cli +``` + +```bash yarn +yarn global add @agentic/platform-cli +``` + + + +## 2. Log in or create an account + + + + +The `agentic` CLI defaults to using GitHub for authentication. + +```bash +agentic login +``` + + + + +```bash +agentic login -e -p +# or +agentic signup -e -p -u +``` + + + + +## 3. Add an Agentic config to your project + + + Make sure your remote MCP server is deployed to a publicly accessible `https` + URL and that the URL supports the Streamable HTTP transport. + + + + + +First, install the `@agentic/platform` package as a dev dependency. + + + +```bash npm +npm i -save-dev @agentic/platform +``` + +```bash pnpm +pnpm add -D @agentic/platform +``` + +```bash bun +bun add -d @agentic/platform +``` + + + +This package exports a `defineConfig` function which makes your config fully-typed and adds nice autocomplete. + +Now, create an `agentic.config.ts` file in the root of your project's source. + +```ts agentic.config.ts +import { defineConfig } from '@agentic/platform' + +export default defineConfig({ + name: '', + description: '', + origin: { + type: 'mcp', + url: '' + } +}) +``` + + + + + +Create an `agentic.config.json` file in the root of your project's source. + +```json agentic.config.json +{ + "name": "", + "description": "", + "origin": { + "type": "mcp", + "url": "" + } +} +``` + + + + + +## 4. Deploy your project + +From the directory where your `agentic.config.ts` or `agentic.config.json` file is located, run: + +```bash +agentic deploy +``` + +Every time you make a change to your project, you can run `agentic deploy` which will create a new immutable preview deployment. These deployments will not affect any published products you may have until you publish them by running `agentic publish`. + + + You'll soon be able to configure a GitHub repository to automatically deploy + your project on changes. Please [let me know](/contact) if you'd like me to + prioritize this feature. + + + + The returned deployment will not have any information about the origin server, + because your origin server is considered hidden once deployed to Agentic's MCP + gateway. + + + + +```json +{ + "id": "depl_m2yl7dpdpc5xk8b3cwvuzkg3", + "createdAt": "2025-06-27 18:14:34.641308+00", + "updatedAt": "2025-06-27 18:14:34.641308+00", + "identifier": "@dev/search@b57dc301", + "hash": "b57dc301", + "published": false, + "description": "Official Google Search tool. Useful for finding up-to-date news and information about any topic.", + "readme": "", + "userId": "user_bhlpuiioipxilpuq7xaoh1ae", + "projectId": "proj_rxs9jorlwolc3seq8enqgrgc", + "tools": [ + { + "name": "search", + "description": "Uses Google Search to return the most relevant web pages for a given query. Useful for finding up-to-date news and information about any topic.", + "inputSchema": { + "type": "object", + "properties": { + "num": { + "type": "integer", + "default": 5, + "description": "Number of results to return" + }, + "type": { + "enum": [ + "search", + "images", + "videos", + "places", + "news", + "shopping" + ], + "type": "string", + "default": "search", + "description": "Type of Google search to perform" + }, + "query": { + "type": "string", + "description": "Search query" + } + }, + "required": ["query"], + "additionalProperties": false, + "$schema": "http://json-schema.org/draft-07/schema#" + }, + "outputSchema": { + "type": "object", + "properties": { + "news": {}, + "images": {}, + "places": {}, + "videos": {}, + "results": {}, + "shopping": {}, + "answerBox": {}, + "knowledgeGraph": {} + }, + "additionalProperties": false, + "$schema": "http://json-schema.org/draft-07/schema#" + } + } + ], + "toolConfigs": [ + { + "name": "search", + "cacheControl": "public, max-age=60, s-maxage=60 stale-while-revalidate=10" + } + ], + "pricingPlans": [ + { + "name": "Free", + "slug": "free", + "rateLimit": { + "interval": 86400, + "limit": 10, + "mode": "approximate", + "enabled": true + }, + "lineItems": [ + { + "slug": "requests", + "usageType": "metered", + "billingScheme": "per_unit", + "unitAmount": 0 + } + ] + }, + { + "name": "Standard", + "slug": "standard", + "interval": "month", + "rateLimit": { + "interval": 1, + "limit": 100, + "mode": "approximate", + "enabled": true + }, + "lineItems": [ + { + "slug": "base", + "usageType": "licensed", + "amount": 1000 + }, + { + "slug": "requests", + "usageType": "metered", + "billingScheme": "tiered", + "tiersMode": "volume", + "tiers": [ + { + "unitAmount": 0, + "upTo": 1000 + }, + { + "unitAmount": 0.01, + "upTo": 50000 + }, + { + "unitAmount": 0.008, + "upTo": 500000 + }, + { + "unitAmount": 0.006, + "upTo": 2500000 + }, + { + "unitAmount": 0.005, + "upTo": "inf" + } + ] + } + ] + } + ], + "pricingIntervals": ["month"], + "defaultRateLimit": { + "interval": 60, + "limit": 1000, + "mode": "approximate", + "enabled": true + } +} +``` + + + +## 5. Test your deployment + +The easiest way to test your deployment is to visit it in your Agentic dashboard: `https://agentic.so/app/projects/`. + +This page will show all the tools available on your deployment and includes a GUI for how to call them with various MCP clients, TS LLM SDKs, Python LLM SDKs, and raw HTTP. + + + Example of calling an Agentic tool + + + + +This example uses the [@agentic/search](https://agentic.so/marketplace/projects/@agentic/search) project's `search` tool. You'll need to replace the project identifier, tool name, and tool arguments with your own, but otherwise, calling your deployment's tools should be pretty straightforward. + + + + +```bash +curl -X POST -H "Content-Type: application/json" -d '{ "query": "example google search" }' https://gateway.agentic.com/mcp/search/search +``` + + + + + +```bash +http -j https://gateway.agentic.com/mcp/search/search query='example google search' +``` + + + + + +## 6. Publish your deployment + +Publishing your deployment will make it publicly available to all Agentic users. This will also enable other users to subscribe to your product using Stripe subscriptions. + +```bash +agentic publish +``` + +The CLI will prompt you to confirm a `semver` version. + +Now, your project will be available at `https://agentic.so/marketplace/projects/`. + +## 7. (Optional) Submit your product to the public Agentic Marketplace + + + Your project will be a live, publicly available product after publishing, complete with all Stripe subscription resources. + +**But it will not be discoverable on the Agentic Marketplace by default.** + +I made this decision during the current beta in order to keep the Agentic Marketplace as high quality and curated as possible. + +If you'd like to submit your product to the Agentic Marketplace, please +[get in touch](/contact). + + diff --git a/docs/publishing/guides/existing-openapi-service.mdx b/docs/publishing/guides/existing-openapi-service.mdx index 918d1728..2b541e06 100644 --- a/docs/publishing/guides/existing-openapi-service.mdx +++ b/docs/publishing/guides/existing-openapi-service.mdx @@ -1,6 +1,355 @@ --- title: Existing OpenAPI Service -description: This guide shows how to publish an existing OpenAPI service to Agentic's MCP Gateway. +description: This guide shows how to publish an existing OpenAPI service to Agentic. --- -**TODO** + + **Prerequisite**: Please install [Node.js](https://nodejs.org) before + proceeding. + + +## 1. Install the Agentic CLI + + + +```bash npm +npm i -g @agentic/platform-cli +``` + +```bash pnpm +pnpm i -g @agentic/platform-cli +``` + +```bash bun +bun install -g @agentic/platform-cli +``` + +```bash yarn +yarn global add @agentic/platform-cli +``` + + + +## 2. Log in or create an account + + + + +The `agentic` CLI defaults to using GitHub for authentication. + +```bash +agentic login +``` + + + + +```bash +agentic login -e -p +# or +agentic signup -e -p -u +``` + + + + +## 3. Add an Agentic config to your project + + + Make sure your remote OpenAPI service is deployed to a publicly accessible + `https` URL, and that your OpenAPI spec is a valid 3.0 or 3.1 spec. + + + + + +First, install the `@agentic/platform` package as a dev dependency. + + + +```bash npm +npm i -save-dev @agentic/platform +``` + +```bash pnpm +pnpm add -D @agentic/platform +``` + +```bash bun +bun add -d @agentic/platform +``` + + + +This package exports a `defineConfig` function which makes your config fully-typed and adds nice autocomplete. + +Now, create an `agentic.config.ts` file in the root of your project's source. + +```ts agentic.config.ts +import { defineConfig } from '@agentic/platform' + +export default defineConfig({ + name: '', + description: '', + origin: { + type: 'openapi', + url: '', + spec: '' + } +}) +``` + + + + + +Create an `agentic.config.json` file in the root of your project's source. + +```json agentic.config.json +{ + "name": "", + "description": "", + "origin": { + "type": "openapi", + "url": "", + "spec": "" + } +} +``` + + + + + +## 4. Deploy your project + +From the directory where your `agentic.config.ts` or `agentic.config.json` file is located, run: + +```bash +agentic deploy +``` + +Every time you make a change to your project, you can run `agentic deploy` which will create a new immutable preview deployment. These deployments will not affect any published products you may have until you publish them by running `agentic publish`. + + + You'll soon be able to configure a GitHub repository to automatically deploy + your project on changes. Please [let me know](/contact) if you'd like me to + prioritize this feature. + + + + + + The returned deployment will not have any information about the origin server, + because your origin server is considered hidden once deployed to Agentic's MCP + gateway. + + +```json +{ + "id": "depl_m2yl7dpdpc5xk8b3cwvuzkg3", + "createdAt": "2025-06-27 18:14:34.641308+00", + "updatedAt": "2025-06-27 18:14:34.641308+00", + "identifier": "@dev/search@b57dc301", + "hash": "b57dc301", + "published": false, + "description": "Official Google Search tool. Useful for finding up-to-date news and information about any topic.", + "readme": "", + "userId": "user_bhlpuiioipxilpuq7xaoh1ae", + "projectId": "proj_rxs9jorlwolc3seq8enqgrgc", + "tools": [ + { + "name": "search", + "description": "Uses Google Search to return the most relevant web pages for a given query. Useful for finding up-to-date news and information about any topic.", + "inputSchema": { + "type": "object", + "properties": { + "num": { + "type": "integer", + "default": 5, + "description": "Number of results to return" + }, + "type": { + "enum": [ + "search", + "images", + "videos", + "places", + "news", + "shopping" + ], + "type": "string", + "default": "search", + "description": "Type of Google search to perform" + }, + "query": { + "type": "string", + "description": "Search query" + } + }, + "required": ["query"], + "additionalProperties": false, + "$schema": "http://json-schema.org/draft-07/schema#" + }, + "outputSchema": { + "type": "object", + "properties": { + "news": {}, + "images": {}, + "places": {}, + "videos": {}, + "results": {}, + "shopping": {}, + "answerBox": {}, + "knowledgeGraph": {} + }, + "additionalProperties": false, + "$schema": "http://json-schema.org/draft-07/schema#" + } + } + ], + "toolConfigs": [ + { + "name": "search", + "cacheControl": "public, max-age=60, s-maxage=60 stale-while-revalidate=10" + } + ], + "pricingPlans": [ + { + "name": "Free", + "slug": "free", + "rateLimit": { + "interval": 86400, + "limit": 10, + "mode": "approximate", + "enabled": true + }, + "lineItems": [ + { + "slug": "requests", + "usageType": "metered", + "billingScheme": "per_unit", + "unitAmount": 0 + } + ] + }, + { + "name": "Standard", + "slug": "standard", + "interval": "month", + "rateLimit": { + "interval": 1, + "limit": 100, + "mode": "approximate", + "enabled": true + }, + "lineItems": [ + { + "slug": "base", + "usageType": "licensed", + "amount": 1000 + }, + { + "slug": "requests", + "usageType": "metered", + "billingScheme": "tiered", + "tiersMode": "volume", + "tiers": [ + { + "unitAmount": 0, + "upTo": 1000 + }, + { + "unitAmount": 0.01, + "upTo": 50000 + }, + { + "unitAmount": 0.008, + "upTo": 500000 + }, + { + "unitAmount": 0.006, + "upTo": 2500000 + }, + { + "unitAmount": 0.005, + "upTo": "inf" + } + ] + } + ] + } + ], + "pricingIntervals": ["month"], + "defaultRateLimit": { + "interval": 60, + "limit": 1000, + "mode": "approximate", + "enabled": true + } +} +``` + + + +## 5. Test your deployment + +The easiest way to test your deployment is to visit it in your Agentic dashboard: `https://agentic.so/app/projects/`. + +This page will show all the tools available on your deployment and includes a GUI for how to call them with various MCP clients, TS LLM SDKs, Python LLM SDKs, and raw HTTP. + + + Example of calling an Agentic tool + + + + +This example uses the [@agentic/search](https://agentic.so/marketplace/projects/@agentic/search) project's `search` tool. You'll need to replace the project identifier, tool name, and tool arguments with your own, but otherwise, calling your deployment's tools should be pretty straightforward. + + + + +```bash +curl -X POST -H "Content-Type: application/json" -d '{ "query": "example google search" }' https://gateway.agentic.com/mcp/search/search +``` + + + + + +```bash +http -j https://gateway.agentic.com/mcp/search/search query='example google search' +``` + + + + + +## 6. Publish your deployment + +Publishing your deployment will make it publicly available to all Agentic users. This will also enable other users to subscribe to your product using Stripe subscriptions. + +```bash +agentic publish +``` + +The CLI will prompt you to confirm a `semver` version. + +Now, your project will be available at `https://agentic.so/marketplace/projects/`. + +## 7. (Optional) Submit your product to the public Agentic Marketplace + + + Your project will be a live, publicly available product after publishing, complete with all Stripe subscription resources. + +**But it will not be discoverable on the Agentic Marketplace by default.** + +I made this decision during the current beta in order to keep the Agentic Marketplace as high quality and curated as possible. + +If you'd like to submit your product to the Agentic Marketplace, please +[get in touch](/contact). + + diff --git a/docs/publishing/origin/index.mdx b/docs/publishing/origin/index.mdx index 129ece3f..393bd7db 100644 --- a/docs/publishing/origin/index.mdx +++ b/docs/publishing/origin/index.mdx @@ -13,7 +13,7 @@ interested in hosting your origin server with Agentic's infrastructure, please Remote origin servers are important because they allow for maximum flexibility with how you author and host your MCP server or OpenAPI service. -By cleanly separating between Agentic's MCP gateway and your remote origin server, Agentic can support origin servers written in any language or frameworka and deployed to any cloud. +By cleanly separating between Agentic's MCP gateway and your remote origin server, Agentic supports origin servers written in any language or framework and deployed to any cloud. diff --git a/docs/publishing/quickstart.mdx b/docs/publishing/quickstart.mdx index e81b2e28..75998b98 100644 --- a/docs/publishing/quickstart.mdx +++ b/docs/publishing/quickstart.mdx @@ -1,6 +1,67 @@ --- title: Quick Start -description: Run one command to turn your existing MCP server or OpenAPI service into a paid MCP product. +description: Deploy your first MCP product to Agentic in minutes. --- -**TODO** +## Do you have an existing API? + + + + Quick start based on an existing MCP server. + + + + Quick start based on an existing OpenAPI service. + + + +## Create a new project from scratch + + + + + + Create a new MCP server and deploy it to Agentic using the TS `fastmcp` package. + + + + Create a new MCP server and deploy it to Agentic using `hono` and `@hono/mcp`. + + + + Create a new OpenAPI server and deploy it to Agentic (as an MCP product!) using `hono` and `@hono/zod-openapi`. + + + + + + + + + + + diff --git a/readme.md b/readme.md index 6c520641..01f1bbcb 100644 --- a/readme.md +++ b/readme.md @@ -42,6 +42,7 @@ - simplify `AgenticToolClient` and only require one package per TS LLM SDK - `createAISDKToolsFromIdentifier(projectIdentifier)` - add really strict free rate-limits to `@agentic/search` +- add urls to db models (projects, deployments, consumers) so CLI users can easily debug ## TODO: Post-MVP