docs: WIP work on mintlify docs

pull/715/head
Travis Fischer 2025-06-27 11:10:25 -05:00
rodzic b140deb203
commit 9a73ec9a83
24 zmienionych plików z 1376 dodań i 26 usunięć

Wyświetl plik

@ -16,8 +16,7 @@ export const copyright = `© ${new Date().getFullYear()} Agentic. All rights res
export const githubUrl = 'https://github.com/transitive-bullshit/agentic' export const githubUrl = 'https://github.com/transitive-bullshit/agentic'
// TODO: make an agentic-specific calendar for this // TODO: make an agentic-specific calendar for this
export const calendarBookingUrl = export const calendarBookingUrl = 'https://cal.com/travis-fischer/15min'
'https://cal.com/travis-fischer/15min?overlayCalendar=true'
export const docsUrl = 'https://docs.agentic.so' export const docsUrl = 'https://docs.agentic.so'
export const docsQuickStartUrl = `${docsUrl}/quick-start` export const docsQuickStartUrl = `${docsUrl}/quick-start`
export const docsMarketplaceUrl = `${docsUrl}/marketplace` export const docsMarketplaceUrl = `${docsUrl}/marketplace`

25
docs/contact.mdx 100644
Wyświetl plik

@ -0,0 +1,25 @@
---
title: Contact
---
Agentic's currently a solo team built and run by [Travis Fischer](https://x.com/transitive_bs). 👋
<Columns cols={2}>
<Card
title='DM me on Twitter / X'
href='https://x.com/transitive_bs'
icon='x-twitter'
/>
<Card
title='Send me an email'
href='mailto:travis@agentic.so'
icon='envelope'
/>
<Card
title='Schedule a call with me'
href='https://cal.com/travis-fischer/15min'
icon='calendar-days'
/>
</Columns>
**TODO**

Wyświetl plik

@ -10,6 +10,10 @@
"background": { "background": {
"image": "/media/bg.png" "image": "/media/bg.png"
}, },
"appearance": {
"mode": "light",
"strict": true
},
"colors": { "colors": {
"primary": "#0D969D", "primary": "#0D969D",
"light": "#13D3DC", "light": "#13D3DC",
@ -39,7 +43,7 @@
"groups": [ "groups": [
{ {
"group": "Getting Started", "group": "Getting Started",
"pages": ["index"] "pages": ["index", "marketplace/index"]
} }
] ]
}, },
@ -48,7 +52,32 @@
"groups": [ "groups": [
{ {
"group": "Getting Started", "group": "Getting Started",
"pages": ["publishing/index"] "pages": [
"publishing/index",
"publishing/quickstart",
"publishing/origin-metadata"
]
},
{
"group": "Publishing Guides",
"pages": [
"publishing/guides/existing-mcp-server",
"publishing/guides/existing-openapi-service",
"publishing/guides/ts-mcp-hono",
"publishing/guides/ts-openapi-hono"
]
},
{
"group": "Config",
"pages": [
"publishing/config/index",
"publishing/config/auth",
"publishing/config/pricing",
"publishing/config/rate-limits",
"publishing/config/caching",
"publishing/config/tool-config",
"publishing/config/examples"
]
} }
] ]
} }
@ -61,7 +90,7 @@
"icon": "house" "icon": "house"
}, },
{ {
"anchor": "Marketplace", "anchor": "MCP Marketplace",
"href": "https://agentic.so/marketplace", "href": "https://agentic.so/marketplace",
"icon": "store" "icon": "store"
}, },

Wyświetl plik

@ -1,15 +1,17 @@
--- ---
title: Home title: Home
description: Agentic is the app store for LLM tools. description: Agentic is the App Store for LLM Tools.
--- ---
<Columns cols={2}> <Columns cols={2}>
<Card title='MCP Marketplace' href='/marketplace' icon='store'> <Card title='MCP Marketplace' href='/marketplace' icon='store'>
The Agentic MCP Marketplace is a curated collection of high quality LLM Agentic's marketplace is a curated collection of high quality LLM tools
tools  all of which are exposed as both MCP servers and simple HTTP APIs.  all of which are exposed as both MCP servers and simple HTTP APIs.
</Card> </Card>
<Card title='Publishing MCPs' href='/publishing/mcp' icon='upload'> <Card title='Publishing MCPs' href='/publishing' icon='upload'>
Publish any MCP server or OpenAPI service to Agentic's MCP Marketplace and Publish any MCP server or OpenAPI service to Agentic's MCP Marketplace and
offer your LLM tools as products to an audience of over 20k AI engineers. offer your LLM tools as products to an audience of over 20k AI engineers.
</Card> </Card>
</Columns> </Columns>
**TODO**

Wyświetl plik

@ -0,0 +1,23 @@
---
title: Quick Start
description: A quick start guide to using MCP tools on the Agentic marketplace.
---
<Columns cols={2}>
<Card
title='Quick Start'
href='/marketplace/quick-start'
icon='rocket-launch'
>
TODO
</Card>
<Card
title='View MCP Marketplace'
href='https://agentic.so/marketplace'
icon='arrow-up-right-from-square'
>
TODO
</Card>
</Columns>
**TODO**

Wyświetl plik

@ -0,0 +1,86 @@
---
title: Auth Config
description: Configure auth for your Agentic product.
---
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).
Currently, Agentic supports the following auth providers:
- Email & password
- GitHub
## 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.
Agentic's MCP gateway will then track all usage of your product based on API keys.
<Tabs>
<Tab title='MCP Origin Server'>
Agentic's MCP Gateway will always include the following metadata in all tool calls within the `_meta.agentic` field.
```ts
export type AgenticMcpRequestMetadata = {
agenticProxySecret: string
sessionId: string
isCustomerSubscriptionActive: boolean
customerId?: string
customerSubscriptionStatus?: string
customerSubscriptionPlan?: string
userId?: string
userEmail?: string
userUsername?: string
userName?: string
userCreatedAt?: string
userUpdatedAt?: string
deploymentId: string
deploymentIdentifier: string
projectId: string
projectIdentifier: string
ip?: string
} & (
| {
// If the customer has an active subscription, these fields are guaranteed
// to be present in the metadata.
isCustomerSubscriptionActive: true
customerId: string
customerSubscriptionStatus: string
userId: string
userEmail: string
userUsername: string
userCreatedAt: string
userUpdatedAt: string
}
| {
// If the customer does not have an active subscription, then the customer
// fields may or may not be present.
isCustomerSubscriptionActive: false
}
)
```
If a customer doesn't provide an API key, they'll default to your `free` pricing plan with `isCustomerSubscriptionActive` set to `false`.
</Tab>
<Tab title='OpenAPI Origin Server'>TODO</Tab>
</Tabs>
## Alpha Features
### MCP OAuth
Agentic's MCP Gateway is designed to interop with MCP's built-in OAuth support, but this functionality is currently in alpha and not enabled publicly by default. If you're interested in using your origin server's MCP authentication support, [please let us know](/contact).
### Custom OAuth Providers
Agentic's MCP Gateway is designed to support any third-party OAuth provider (Google, Twitter / X, Slack, Airtable, Shopify, etc), but this functionality is currently in alpha and not enabled publicly by default.
If you're interested in using a different OAuth provider or want your customers to use your own OAuth client credentials or custom scopes, [please let us know](/contact).

Wyświetl plik

@ -0,0 +1,94 @@
---
title: Caching Config
description: Configure caching for your Agentic product'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.
Agentic uses Cloudflare's global edge cache for caching, which guarantees unmatched global performance.
## Enabling Caching
You can enable caching for individual tools by setting [pure](/publishing/config/tool-config#param-pure) or [cacheControl](/publishing/config/tool-config#param-cache-control) on the tool's config.
## Cache Keys
Cache keys for tool calls are generated by normalizing the tool call's input, regardless of whether the tool call was made via `HTTP POST`, `HTTP GET`, or `MCP`.
Tool call args will be hashed using a deterministic, stable JSON serialization algorithm, so tool calls with semantically identical input will have identical cache keys.
## Disabling Caching
Individual tool calls can disable caching by setting the standard `Cache-Control` header to `no-store` or `no-cache`.
<Note>
Note that by default, caching is disabled for all tools. You must explicitly
enable caching for each tool in your Agentic project config.
</Note>
## Examples
<Tabs>
<Tab title="Pure Tool">
```ts agentic.config.ts
import { defineConfig } from '@agentic/platform'
// In this example, `my-tool` is marked as pure which means its responses
// will be cached aggressively for identical requests using `cache-control`
// `public, max-age=31560000, s-maxage=31560000, stale-while-revalidate=3600`
export default defineConfig({
// ...
toolConfigs: [
{
name: 'my-tool',
pure: true
}
]
})
```
</Tab>
<Tab title="Custom Cache-Control">
```ts agentic.config.ts
import { defineConfig } from '@agentic/platform'
// In this example, `my-tool` is using a custom `Cache-Control` header to
// cache responses for 60 seconds.
export default defineConfig({
// ...
toolConfigs: [
{
name: 'my-tool',
cacheControl: 'public, max-age=60, s-maxage=60 stale-while-revalidate=10'
}
]
})
```
</Tab>
<Tab title="Disabling Caching">
```ts agentic.config.ts
import { defineConfig } from '@agentic/platform'
// In this example, `my-tool` results will never be cached.
// Note that this is the default behavior for all tools unless caching is
// explicitly enabled for a tool.
export default defineConfig({
// ...
toolConfigs: [
{
name: 'my-tool',
cacheControl: 'no-cache'
}
]
})
```
</Tab>
</Tabs>

Wyświetl plik

@ -0,0 +1,6 @@
---
title: Examples
description: Example Agentic config files.
---
**TODO**

Wyświetl plik

@ -0,0 +1,169 @@
---
title: Overview
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.
<Note>
Configuring your project can feel a little overwhelming. Feel free to [reach
out to us](/contact) if you're considering using Agentic's MCP Gateway, and
I'd be happy to help walk you through getting your product set up for success.
</Note>
## Config Fields
<ResponseField name='name' type='string' required>
Display name for your project.
Max length 1024 characters.
</ResponseField>
<ResponseField name='slug' type='string' required>
Unique project slug.
Must be ascii-only, lower-case, and kebab-case with no spaces between 1 and 256 characters.
The project's fully qualified identifier will be `@namespace/slug`, where
the `namespace` is determined by the author's `username` or team slug.
If not provided, it will be derived by slugifying `name`.
</ResponseField>
<ResponseField name='description' type='string' required>
Short description of the project.
Should be no longer than a few lines.
</ResponseField>
<ResponseField name='version' type='string'>
Optional semantic version of the project as a [semver](https://semver.org) string.
Examples: `1.0.0`, `0.0.1`, `5.0.1`, etc.
</ResponseField>
<ResponseField name='readme' type='string'>
Optional embedded markdown readme documenting the project. Supports
GitHub-flavored markdown.
</ResponseField>
<ResponseField name='iconUrl' type='string'>
Optional logo image URL to use for the project. Logos should have a square
aspect ratio.
</ResponseField>
<ResponseField name='sourceUrl' type='string'>
Optional URL to the source code of the project (eg, GitHub repo).
</ResponseField>
<ResponseField name='origin' type='object' required>
Origin API adapter used to configure the origin API server downstream from
Agentic's API gateway.
<Expandable title="properties" defaultOpen>
<Tabs>
<Tab title="MCP origin server">
<ResponseField name="type" type="string" required>
The type of origin server. `mcp` in this case.
</ResponseField>
<ResponseField name="url" type="string" required>
Required base URL of the externally hosted origin MCP server.
This URL must be accessible from Agentic's API gateway and support the Streamable HTTP transport.
Must be a valid `https` URL.
</ResponseField>
</Tab>
<Tab title="OpenAPI origin server">
<ResponseField name="type" type="string" required>
The type of origin server. `openapi` in this case.
</ResponseField>
<ResponseField name="url" type="string" required>
Required base URL of the externally hosted origin API server.
Must be a valid `https` URL.
</ResponseField>
<ResponseField name="spec" type="string" required>
Local file path or URL to an OpenAPI 3.x spec describing the origin API server.
May also be an embedded string containing a JSON stringified OpenAPI 3.x spec.
Note that older OpenAPI versions are not supported.
</ResponseField>
</Tab>
</Tabs>
</Expandable>
</ResponseField>
<ResponseField name='pricingPlans' type='array'>
List of PricingPlans configuring which Stripe subscriptions should be available for the project.
Defaults to a single free plan which is useful for developing and testing your project.
See [PricingPlan](/publishing/config/pricing#pricing-plan-config) for details.
</ResponseField>
<ResponseField name='pricingIntervals' type='array'>
Optional list of billing intervals to enable in pricing plans.
Defaults to a single monthly interval `['month']`.
To add support for annual pricing plans, for example, you can use:
`['month', 'year']`.
Note that for every pricing interval, you must define a corresponding set
of PricingPlans in the `pricingPlans` array. If you only have one pricing
interval (like the default `month` interval), `pricingPlans` don't need to
specify their `interval` property. Otherwise, all PricingPlans must
specify their `interval` property to differentiate between different
pricing intervals.
</ResponseField>
<ResponseField name='defaultRateLimit' type='object'>
Optional default rate limits to enforce across all pricing plans.
If not set, a default platform rate-limit of 1000 requests per minute per customer will be used.
To disable the default rate-limit, set `defaultRateLimit.enabled` to
`false`.
Note that pricing-plan-specific rate-limits override this default (via
`pricingPlans`), and tool-specific rate-limits may override both default
and pricing-plan-specific rate-limits (via `toolConfigs`).
See [Rate Limits](/publishing/config/rate-limits) for more details.
</ResponseField>
<ResponseField name='toolConfigs' type='array'>
Optional list of tool configs to override the default behavior of specific tools.
See [Tool Config](/publishing/config/tool-config) for details.
</ResponseField>
## Config Help
<Note>
Configuring your project can feel a little overwhelming. Feel free to [reach
out to us](/contact) if you're considering using Agentic's MCP Gateway, and
I'd be happy to help walk you through getting your product set up for success.
</Note>

Wyświetl plik

@ -0,0 +1,428 @@
---
title: Pricing Config
description: Configure pricing for your Agentic product.
---
Charge for your Agentic product with a flexible, declarative pricing model built on top of [Stripe](https://stripe.com).
Agentic supports almost any combination of **fixed** and **usage-based billing** billing models, both at the MCP level, at the tool-call level, and at the custom metric level (e.g., tokens, image transformations, etc).
<Note>
Pricing can feel a little complicated to set up. Feel free to [reach out to
us](/contact) once you're ready to start charging for your product, and I'd be
happy to help you set everything up.
</Note>
## Pricing Plan Config
<ResponseField name="name" type="string" required>
Display name for the pricing plan.
Examples: "Free", "Starter Monthly", "Pro Annual", etc.
</ResponseField>
<ResponseField name='slug' type='string' required>
A unique slug for the pricing plan which acts as a stable identifier across deployments.
Should be lower-kebab-cased.
Should be stable across deployments.
For all plans aside from `free`, the `slug` should include the `interval`
as a suffix so pricing plans can be uniquely differentiated from each
other across billing intervals.
Examples: `free`, `starter-monthly`, `pro-annual`, etc.
</ResponseField>
<ResponseField name='interval' type='string' default='month'>
The frequency at which this subscription is billed.
One of `day`, `week`, `month`, or `year`.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-recurring-interval)
</ResponseField>
<ResponseField name='description' type='string'>
Optional description of the pricing plan (UI-only).
</ResponseField>
<ResponseField name='features' type='array'>
Optional list of features of the pricing plan (UI-only; array of strings).
</ResponseField>
<ResponseField name='trialPeriodDays' type='number'>
Optional number of days for a free trial period when a customer signs up for a
new subscription.
[Stripe docs](https://docs.stripe.com/api/subscriptions/create?api-version=2025-05-28.preview#create_subscription-trial_period_days)
</ResponseField>
<ResponseField name='rateLimit' type='object'>
Optional rate limit to enforce for customers on this pricing plan.
You can use this to limit the number of API requests that can be made by
a customer during a given interval.
If not set, the pricing plan will inherit the default platform rate-limit
set by `defaultRateLimit` in the Agentic project config.
You can disable rate-limiting for this pricing plan by setting
`rateLimit.enabled` to `false`.
See [Rate Limits](/publishing/config/rate-limits) for more details.
</ResponseField>
<ResponseField name='lineItems' type='array' required>
List of LineItems which are included in the PricingPlan.
Note: Agentic currently supports a max of 20 LineItems per pricing plan.
See [PricingPlanLineItem](#pricing-plan-line-item-config) for details.
</ResponseField>
## Pricing Plan Line Item Config
Each Pricing Plan Line Item corresponds to one [Stripe Product](https://docs.stripe.com/api/products/object?api-version=2025-05-28.preview), one [Stripe Price](https://docs.stripe.com/api/prices/object?api-version=2025-05-28.preview), and possibly one [Stripe Meter](https://docs.stripe.com/api/billing/meter/object?api-version=2025-05-28.preview) if the line-item is `metered`.
<ResponseField name='slug' type='string' required>
Slugs act as the primary key for LineItems. They should be lower-cased and
kebab-cased ("base", "requests", "image-transformations").
The `base` slug is reserved for a plan's default `licensed` line-item.
The `requests` slug is reserved for charging using `metered` billing based
on the number of request made during a given billing interval.
All other PricingPlanLineItem `slugs` are considered custom LineItems.
Should be stable across deployments, so if a slug refers to one type of
product / line-item / metric in one deployment, it should refer to the same
product / line-item / metric in future deployments, even if they are
configured differently. If you are switching between a licensed and metered
line-item across deployments, they must use different slugs.
</ResponseField>
<ResponseField name='label' type='string'>
Optional label for the line-item which will be displayed on customer bills.
If unset, the line-item's `slug` will be used as the label.
[Stripe Docs](https://docs.stripe.com/api/products/object?api-version=2025-02-24.acacia#product_object-unit_label)
</ResponseField>
<ResponseField name='usageType' type='string' required>
The type of usage to charge for. Either `licensed` or `metered`.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-recurring-usage_type)
</ResponseField>
<Tabs>
<Tab title="Licensed Line Item">
Licensed line-items are used to charge for **fixed-price services**.
<ResponseField name='usageType' type='string' required>
The type of usage to charge for. `licensed` in this case.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-recurring-usage_type)
</ResponseField>
<ResponseField name='amount' type='number' required>
The fixed amount to charge per billing interval.
Specified in the smallest currency unit (e.g. cents for USD).
So 100 = \$1.00 USD, 1000 = \$10.00 USD, etc.
[Stripe docs](https://docs.stripe.com/api/prices/create?api-version=2025-05-28.preview#create_price-unit_amount)
</ResponseField>
</Tab>
<Tab title="Metered Line Item">
Metered line-items are used to charge for **usage-based services**.
<ResponseField name='usageType' type='string' required>
The type of usage to charge for. `metered` in this case.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-recurring-usage_type)
</ResponseField>
<ResponseField name='unitLabel' type='string'>
Optional label for the line-item which will be displayed on customer bills.
If unset, the line-item's `slug` will be used as the unit label.
[Stripe Docs](https://docs.stripe.com/api/products/object?api-version=2025-02-24.acacia#product_object-unit_label)
</ResponseField>
<ResponseField name='billingScheme' type='string' required>
Describes how to compute the price per period. Either `per_unit` or `tiered`.
`per_unit` indicates that the fixed amount (specified in `unitAmount`) will be charged per unit of total usage.
`tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using `tiers` and `tiersMode`.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-billing_scheme)
</ResponseField>
<ResponseField name='unitAmount' type='number' required>
The fixed amount to charge per unit of usage.
Only applicable for `per_unit` billing schemes.
Specified in the smallest currency unit (e.g. cents for USD).
So 100 = \$1.00 USD, 1000 = \$10.00 USD, etc.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-unit_amount)
</ResponseField>
<ResponseField name='tiersMode' type='string'>
Defines if the tiering price should be `graduated` or `volume` based.
In `volume`-based tiering, the maximum quantity within a period
determines the per unit price.
In `graduated`-based tiering, the per-unit price changes successively
as the quantity grows.
This field requires `billingScheme` to be set to `tiered`.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-tiers_mode)
</ResponseField>
<ResponseField name='tiers' type='array'>
Pricing tiers for `tiered` billing schemes.
This field requires `billingScheme` to be set to `tiered`.
One of `unitAmount` or `flatAmount` must be provided, but not both.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-tiers)
<Expandable title="properties">
<ResponseField name='upTo' type='number' required>
The maximum quantity of usage for this tier.
Should be a number or `inf` for the maximum tier.
</ResponseField>
<ResponseField name='unitAmount' type='number'>
The fixed amount to charge per unit of usage for this pricing tier.
Specified in the smallest currency unit (e.g. cents for USD).
So 100 = \$1.00 USD, 1000 = \$10.00 USD, etc.
</ResponseField>
<ResponseField name='flatAmount' type='number'>
The fixed amount to charge per billing interval for this pricing tier.
Specified in the smallest currency unit (e.g. cents for USD).
So 100 = \$1.00 USD, 1000 = \$10.00 USD, etc.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name='defaultAggregation' type='object' default="{ formula: 'sum' }">
Specifies how events are aggregated for the Stripe Meter.
[Stripe docs](https://docs.stripe.com/api/billing/meter/create?api-version=2025-02-24.acacia#create_billing_meter-default_aggregation)
<Expandable title="properties">
<ResponseField name='formula' type='string' default='sum' required>
Specifies how events are aggregated for a Stripe Meter.
Allowed values:
- `sum` - Sum each event's value during the period.
- `count` - Count the number of events during the period.
If not set, `sum` will be used.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name='transformQuantity' type='object'>
Optional transformation to apply to the reported usage or set quantity before computing the amount billed.
Cannot be combined with `tiers`.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-transform_quantity)
<Expandable title="properties">
<ResponseField name='divideBy' type='number' required>
Divide usage by this number.
Must be a positive number.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-transform_quantity-divide_by)
</ResponseField>
<ResponseField name='round' type='string' required>
After division, either round the result `up` or `down`.
[Stripe docs](https://docs.stripe.com/api/prices/object?api-version=2025-02-24.acacia#price_object-transform_quantity-round)
</ResponseField>
</Expandable>
</ResponseField>
</Tab>
</Tabs>
## Example Pricing Plans
<Tabs>
<Tab title="Default Free Plan">
This example shows a free monthly pricing plan which is used by default for projects that don't specify any pricing plans.
```ts agentic.config.ts
import { defineConfig } from '@agentic/platform'
export default defineConfig({
// ...
pricingPlans: [
{
name: 'Free',
slug: 'free',
lineItems: [
{
slug: 'base',
usageType: 'licensed',
amount: 0
}
]
}
]
})
```
</Tab>
<Tab title="Freemium + $4.99 Basic Plan">
This example has 2 pricing plans, the default free plan and a fixed-price $4.99 / month basic plan with a 7-day trial.
```ts agentic.config.ts
import { defaultFreePricingPlan, defineConfig } from '@agentic/platform'
export default defineConfig({
// ...
pricingPlans: [
defaultFreePricingPlan,
{
name: 'Basic',
slug: 'basic',
trialPeriodDays: 7,
lineItems: [
{
slug: 'base',
usageType: 'licensed',
amount: 499 // $4.99 USD
}
]
}
]
})
```
</Tab>
<Tab title="Pay-As-You-Go">
```ts agentic.config.ts
import { defineConfig } from '@agentic/platform'
export default defineConfig({
// ...
pricingPlans: [
{
name: 'Free',
slug: 'free',
lineItems: [
{
slug: 'base',
usageType: 'licensed',
amount: 0
}
],
// Free but limited to 20 requests per day
rateLimit: {
limit: 20,
interval: '1d'
}
},
{
name: 'Pay-As-You-Go',
slug: 'pay-as-you-go',
lineItems: [
{
slug: 'requests',
usageType: 'metered',
billingScheme: 'tiered',
tiersMode: 'volume',
// $0.00467 USD per request up to 999 requests per month
// then $0.00053 USD for unlimited further requests that month
tiers: [
{
upTo: 999,
unitAmount: 0.467
},
{
upTo: 'inf',
unitAmount: 0.053
}
]
}
],
// Limit to 1000 requests per day
rateLimit: {
limit: 1000,
interval: '1d'
}
}
]
})
```
</Tab>
</Tabs>
## Pricing Help
<Note>
Pricing can feel a little complicated to set up. Feel free to [reach out to
us](/contact) once you're ready to start charging for your product, and I'd be
happy to help you set everything up.
</Note>

Wyświetl plik

@ -0,0 +1,86 @@
---
title: Rate Limit Config
description: Configure rate-limits for your Agentic product.
---
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.
## Rate Limit Config
<ResponseField name='enabled' type='boolean' required>
Whether to enable rate limiting for this pricing plan.
</ResponseField>
<ResponseField name="interval" type="string" required>
The interval at which the rate limit is applied.
Either a positive integer expressed in seconds or a valid positive [ms](https://github.com/vercel/ms) string (eg, "10s", "1m", "8h", "2d", "1w", "1y", etc).
</ResponseField>
<ResponseField name='limit' type='number' required>
The maximum number of API requests per interval (unitless).
</ResponseField>
<ResponseField name="mode" type="string" default="approximate">
How to enforce the rate limit: "strict" (more precise but slower) or "approximate" (the default; faster and asynchronous but less precise).
The default rate-limiting mode is `approximate`, which means that requests
are allowed to proceed immediately, with the limit being enforced
asynchronously in the background. This is much faster than synchronous
mode, but it is less consistent if precise adherence to rate-limits is
required.
With `strict` mode, requests are blocked until the current limit has
been confirmed. The downside with this approach is that it introduces
more latency to every request by default. The advantage is that it is
more precise and consistent.
</ResponseField>
## Example Rate Limits
<Tabs>
<Tab title="Default">
The default platform rate limit for `requests` is a limit of 1000 requests per minute per customer.
```ts
{
enabled: true,
interval: '1m',
limit: 1000,
mode: 'approximate'
}
```
</Tab>
<Tab title="Strict daily">
This example rate limit restricts customers to 100 requests per day. It uses `strict` mode which adds a little extra latency but guarantees that customers will never exceed the limit.
```ts
{
enabled: true,
interval: '1d',
limit: 100,
mode: 'strict'
}
```
</Tab>
<Tab title="Disabled">
This is an example of a disabled rate limit.
```ts
{
enabled: false
}
```
</Tab>
</Tabs>

Wyświetl plik

@ -0,0 +1,153 @@
---
title: Tool Config
description: Configure tool-specific settings for your Agentic product.
---
Optional list of tool configs to override the default behavior of specific tools.
Make sure the tool `name` matches the origin server's tool names, either via its MCP server or OpenAPI operationIds.
Tool names are expected to be unique and stable across deployments.
With `toolConfigs`, tools can be disabled, set custom rate-limits, customize reporting usage for metered billing, and they can also override behavior for different pricing plans.
For example, you may want to disable certain tools on a `free` pricing plan or remove the rate-limit for a specific tool on a `pro` pricing plan while keeping the defualt rate-limit in place for other tools.
Note that tool-specific configs override the defaults defined in pricing plans.
If a tool is defined on the origin server but not specified in `toolConfigs`, it will use the default behavior of the Agentic API gateway.
## Tool Config
<ResponseField name='name' type='string' required>
The name of the tool, which acts as a unique, stable identifier for the tool
across deployments.
</ResponseField>
<ResponseField name='enabled' type='boolean' default='true'>
Whether this tool should be enabled for all customers (default).
If you want to hide a tool from customers but still have it present on your origin server, set this to `false` for the given tool.
</ResponseField>
<ResponseField name='pure' type='boolean' default='false'>
Whether this tool's output is deterministic and idempotent given the same input.
If `true`, tool outputs will be cached aggressively for identical requests, though origin server response headers can still override this behavior on a per-request basis.
If `false`, tool outputs will be cached according to the origin server's response headers on a per-request basis.
</ResponseField>
<ResponseField name='cacheControl' type='string'>
A custom `Cache-Control` header to use for caching this tool's responses.
If set, this field overrides `pure`.
If not set and `pure` is `true`, the gateway will default to: `public, max-age=31560000, s-maxage=31560000, stale-while-revalidate=3600` (cache publicly for up to 1 year).
If not set and `pure` is `false`, the gateway will default to `no-store` which will disable caching. This is the default gateway behavior for tools (no caching).
Note that origin server response headers may also choose to disable caching on a per-request basis.
</ResponseField>
<ResponseField name='reportUsage' type='boolean' default='true'>
Whether calls to this tool should be reported as usage for the default `requests` line-item's metered billing.
Note: This is only relevant if the customer's active pricing plan includes a `requests` line-item.
</ResponseField>
<ResponseField name='rateLimit' type='object'>
Customize the default `requests`-based rate-limiting for this tool.
To disable rate-limiting for this tool, set `rateLimit.enabled` to `false`.
If not set, the default rate-limiting for the active pricing plan will be used.
See [Rate Limits](/publishing/config/rate-limits) for details.
</ResponseField>
<ResponseField name='inputSchemaAdditionalProperties' type='boolean'>
Whether to allow additional properties in the tool's input schema.
The default MCP spec allows additional properties. Set this to `false` if you want your tool to be more strict.
Note: This is only relevant if the tool has defined an `inputSchema`.
</ResponseField>
<ResponseField name='outputSchemaAdditionalProperties' type='boolean'>
Whether to allow additional properties in the tool's output schema.
The default MCP spec allows additional properties. Set this to `false` if you want your tool to be more strict.
Note: This is only relevant if the tool has defined an `outputSchema`.
</ResponseField>
<ResponseField name='pricingPlanOverrides' type='object'>
Allows you to override this tool's behavior or disable it entirely for different pricing plans.
This is a map from PricingPlan `slug` to PricingPlanToolOverride.
```ts agentic.config.ts
import { defineConfig } from '@agentic/platform'
// In this example, `my-tool` is disabled for the `free` pricing plan.
export default defineConfig({
// ...
toolConfigs: [
{
name: 'my-tool',
pricingPlanOverridesMap: {
free: {
enabled: false
}
}
}
]
})
```
<Expandable title="PricingPlanToolOverride">
<ResponseField name='enabled' type='boolean'>
Whether this tool should be enabled for the given pricing plan.
If `undefined`, will use the tool's default enabled state.
</ResponseField>
<ResponseField name='reportUsage' type='boolean'>
Whether to report default `requests` usage for metered billing for customers on a given pricing plan.
Note: This is only relevant if the pricing plan includes a `requests` line-item.
If `undefined`, will use the tool's default reportUsage state.
</ResponseField>
<ResponseField name='rateLimit' type='object'>
Customize or disable rate limits for this tool for customers on a given pricing plan.
To disable rate-limiting for this tool on a given pricing plan, set `rateLimit.enabled` to `false`.
See [Rate Limits](/publishing/config/rate-limits) for details.
</ResponseField>
</Expandable>
</ResponseField>
## Config Help
<Note>
Configuring your project can feel a little overwhelming with the amount of
options available. Feel free to [reach out to us](/contact) if you're
considering using Agentic's MCP Gateway, and I'd be happy to help walk you
through getting your product set up for success.
</Note>

Wyświetl plik

@ -0,0 +1,6 @@
---
title: Existing MCP Server
description: This guide shows how to publish an existing MCP server to Agentic's MCP Gateway.
---
**TODO**

Wyświetl plik

@ -0,0 +1,6 @@
---
title: Existing OpenAPI Service
description: This guide shows how to publish an existing OpenAPI service to Agentic's MCP Gateway.
---
**TODO**

Wyświetl plik

@ -0,0 +1,6 @@
---
title: TS MCP Hono
description: This guide shows how to publish an MCP server to Agentic's MCP Gateway using TypeScript and Hono's MCP middleware.
---
**TODO**

Wyświetl plik

@ -0,0 +1,6 @@
---
title: TS OpenAPI Hono
description: This guide shows how to publish an OpenAPI service to Agentic's MCP Gateway using TypeScript and Hono's OpenAPI support.
---
**TODO**

Wyświetl plik

@ -5,3 +5,5 @@ description: Your API → Paid MCP, Instantly.
Run one command to turn any MCP server or OpenAPI service into a paid MCP Run one command to turn any MCP server or OpenAPI service into a paid MCP
product, <em>with built-in distribution to over 20k AI engineers</em>. product, <em>with built-in distribution to over 20k AI engineers</em>.
**TODO**

Wyświetl plik

@ -0,0 +1,219 @@
---
title: Origin Metadata
description: Agentic's MCP Gateway passes metadata to your origin server.
---
<Tabs>
<Tab title='MCP Origin Server'>
Agentic's MCP Gateway will always include the following metadata in all tool calls within the `_meta.agentic` field.
```ts
export type AgenticMcpRequestMetadata = {
agenticProxySecret: string
sessionId: string
isCustomerSubscriptionActive: boolean
customerId?: string
customerSubscriptionStatus?: string
customerSubscriptionPlan?: string
userId?: string
userEmail?: string
userUsername?: string
userName?: string
userCreatedAt?: string
userUpdatedAt?: string
deploymentId: string
deploymentIdentifier: string
projectId: string
projectIdentifier: string
ip?: string
} & (
| {
// If the customer has an active subscription, these fields are guaranteed
// to be present in the metadata.
isCustomerSubscriptionActive: true
customerId: string
customerSubscriptionStatus: string
userId: string
userEmail: string
userUsername: string
userCreatedAt: string
userUpdatedAt: string
}
| {
// If the customer does not have an active subscription, then the customer
// fields may or may not be present.
isCustomerSubscriptionActive: false
}
)
```
</Tab>
<Tab title='OpenAPI Origin Server'>
Agentic's MCP Gateway will always include the following headers for all tool calls to your origin server.
<ResponseField name='x-agentic-proxy-secret' type='string' required>
The secret key of your Agentic project. This is used to guarantee that HTTP
requests are actually coming from Agentic's MCP Gateway, and not from
third-party actors.
You can find this secret key in your Agentic project's dashboard settings.
</ResponseField>
<ResponseField name='x-agentic-customer-id' type='string'>
The ID of the customer in Agentic's database.
</ResponseField>
<ResponseField
name='x-agentic-is-customer-subscription-active'
type='string'
required
default='false'
>
Whether the customer has an active subscription. Will be either `true` or
`false`.
</ResponseField>
<ResponseField
name='x-agentic-customer-subscription-status'
type='string'
required
default='incomplete'
>
The [Stripe status](https://docs.stripe.com/api/subscriptions/object#subscription_object-status) of the customer's subscription.
Possible values are `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`, or `paused`.
</ResponseField>
<ResponseField
name='x-agentic-customer-subscription-plan'
type='string'
required
default='free'
>
The slug of the customer's subscription pricing plan.
</ResponseField>
<ResponseField name='x-agentic-user-id' type='string'>
The ID of the user in Agentic's database.
</ResponseField>
<ResponseField name='x-agentic-user-email' type='string'>
The email of the user in Agentic's database.
</ResponseField>
<ResponseField name='x-agentic-user-username' type='string'>
The username of the user in Agentic's database.
</ResponseField>
<ResponseField name='x-agentic-user-name' type='string'>
The name of the user in Agentic's database.
</ResponseField>
<ResponseField name='x-agentic-user-created-at' type='string'>
The date and time the user was created in Agentic's database.
</ResponseField>
<ResponseField name='x-agentic-user-updated-at' type='string'>
The date and time the user was last updated in Agentic's database.
</ResponseField>
<ResponseField name='x-agentic-project-id' type='string' required>
The ID of the project in Agentic's database. (`proj_...`)
</ResponseField>
<ResponseField name='x-agentic-project-identifier' type='string' required>
The public identifier of the target project in Agentic's database.
(`@username/project-name`)
</ResponseField>
<ResponseField name='x-agentic-deployment-id' type='string' required>
The ID of the target deployment in Agentic's database. (`depl_...`)
</ResponseField>
<ResponseField name='x-agentic-deployment-identifier' type='string' required>
The public identifier of the target deployment in Agentic's database.
(`@username/project-name@<deployment-hash>`)
</ResponseField>
</Tab>
</Tabs>
## Unauthenticated requests
If a customer doesn't provide an API key for their MCP or HTTP call, Agentic's MCP Gateway will default them to your project's `free` pricing plan with `isCustomerSubscriptionActive` set to `false`.
This means they'll be subject to your project's `free` pricing plan's [rate limits](/publishing/config/rate-limits), which is important to protect your origin server from abuse.
## Securing your origin server
Agentic's MCP Gateway will always pass a proxy secret when making tool calls to your origin server (either as `_meta.agentic.agenticProxySecret` for MCP origin servers or as an `x-agentic-proxy-secret` header for OpenAPI origin servers).
You can find this secret key in your Agentic project's dashboard settings.
You'll want to set this secret key in your origin server's environment variables and use it to protect against unauthorized requests.
Note that this is only necessary if your origin server is deployed externally to a public network.
### Securing an MCP origin server
```ts
// This is example pseudocode for how you might protect your origin MCP
// server to ensure only calls from Agentic's MCP Gateway are allowed.
if (
(_meta?.agentic as any)?.agenticProxySecret !==
process.env.AGENTIC_PROXY_SECRET
) {
return {
content: [
{
type: 'text',
text: 'Unauthorized'
}
]
}
}
```
### Securing an OpenAPI origin server
```ts
// This is example pseudocode for how you might protect your origin OpenAPI
// service to ensure only calls from Agentic's MCP Gateway are allowed.
if (
request.headers.get('x-agentic-proxy-secret') !==
process.env.AGENTIC_PROXY_SECRET
) {
return {
status: 401,
body: {
error: 'Unauthorized'
}
}
}
```
### Restricting IP addresses
You can also protecting your origin server by restricting HTTP calls to specific IP addresses used by Agentic's MCP gateway.
This is currently a private beta feature. If you're interested in using it, please [get in touch](/contact).
### Signed HTTP requests
You can also protecting your origin OpenAPI server by requiring all HTTP requests to be signed with your project's proxy secret.
This is currently a private beta feature. If you're interested in using it, please [get in touch](/contact).
### Signed MCP requests
[MCP currently doesn't support signed requests](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/461).
If you're interested in this feature, please [get in touch](/contact).

Wyświetl plik

@ -0,0 +1,6 @@
---
title: Quick Start
description: Run one command to turn your existing MCP server or OpenAPI service into a paid MCP product.
---
**TODO**

Wyświetl plik

@ -38,6 +38,11 @@ export default defineConfig({
name: 'Standard', name: 'Standard',
slug: 'standard', slug: 'standard',
lineItems: [ lineItems: [
{
slug: 'base',
usageType: 'licensed',
amount: 1000
},
{ {
slug: 'requests', slug: 'requests',
usageType: 'metered', usageType: 'metered',

Wyświetl plik

@ -72,11 +72,6 @@ export default {
.passthrough().shape .passthrough().shape
}, },
async (args, { _meta }) => { async (args, { _meta }) => {
console.log('search call', {
args,
_meta
})
// Make sure the request is coming from Agentic // Make sure the request is coming from Agentic
if ( if (
(_meta?.agentic as any)?.agenticProxySecret !== (_meta?.agentic as any)?.agenticProxySecret !==

Wyświetl plik

@ -1,8 +1,7 @@
import { defineConfig } from '@agentic/platform' import { defineConfig } from '@agentic/platform'
export default defineConfig({ export default defineConfig({
name: 'Test Basic MCP', name: 'test-basic-mcp',
slug: 'test-basic-mcp',
origin: { origin: {
type: 'mcp', type: 'mcp',
url: 'https://agentic-basic-mcp-test.onrender.com/mcp' url: 'https://agentic-basic-mcp-test.onrender.com/mcp'

Wyświetl plik

@ -188,7 +188,7 @@ To add support for annual pricing plans, for example, you can use: \`['month', '
.default(['month']), .default(['month']),
/** /**
* Optional default rate limits to enforce for all pricing plans. * Optional default rate limits to enforce across all pricing plans.
* *
* To disable the default rate-limit, set `defaultRateLimit.enabled` to * To disable the default rate-limit, set `defaultRateLimit.enabled` to
* `false`. * `false`.
@ -202,7 +202,8 @@ To add support for annual pricing plans, for example, you can use: \`['month', '
.default(defaultRequestsRateLimit), .default(defaultRequestsRateLimit),
/** /**
* Optional list of tool configs to customize the behavior of tools. * Optional list of tool configs to override the default behavior of
* specific tools.
* *
* Make sure the tool `name` matches the origin server's tool names, either * Make sure the tool `name` matches the origin server's tool names, either
* via its MCP server or OpenAPI operationIds. * via its MCP server or OpenAPI operationIds.

Wyświetl plik

@ -233,14 +233,13 @@ export const pricingPlanMeteredLineItemSchema =
.object({ .object({
/** /**
* Specifies how events are aggregated for a Stripe Meter. * Specifies how events are aggregated for a Stripe Meter.
* Allowed values are `count` to count the number of events, `sum` * Allowed values are `count` to count the number of events and `sum`
* to sum each event's value and `last` to take the last event's * to sum each event's value .
* value in the window.
* *
* Defaults to `sum`. * Defaults to `sum`.
*/ */
formula: z formula: z
.union([z.literal('sum'), z.literal('count'), z.literal('last')]) .union([z.literal('sum'), z.literal('count')])
.default('sum') .default('sum')
}) })
.optional(), .optional(),
@ -482,7 +481,7 @@ export const pricingPlanSchema = z
.string() .string()
.nonempty() .nonempty()
.describe( .describe(
'Human-readable name for the pricing plan (eg, "Free", "Starter Monthly", "Pro Annual", etc)' 'Display name for the pricing plan (eg, "Free", "Starter Monthly", "Pro Annual", etc)'
) )
.openapi('name', { example: 'Starter Monthly' }), .openapi('name', { example: 'Starter Monthly' }),
@ -550,13 +549,13 @@ export const pricingPlanSchema = z
rateLimit: rateLimitSchema.optional(), rateLimit: rateLimitSchema.optional(),
/** /**
* List of custom LineItems which are included in the PricingPlan. * List of LineItems which are included in the PricingPlan.
* *
* Note: we currently support a max of 20 LineItems per plan. * Note: Agentic currently supports a max of 20 LineItems per pricing plan.
*/ */
lineItems: z.array(pricingPlanLineItemSchema).nonempty().max(20, { lineItems: z.array(pricingPlanLineItemSchema).nonempty().max(20, {
message: message:
'Stripe Checkout currently supports a max of 20 LineItems per subscription.' 'Agentic currently supports a max of 20 LineItems per pricing plan.'
}) })
}) })
.describe( .describe(