diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index a5c9dc2..ed66725 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -30,12 +30,14 @@ ** xref:mcp:test-tools.adoc[Test a server's tools] ** xref:mcp:managed/index.adoc[Managed catalog] *** xref:mcp:managed/managed-catalog.adoc[Catalog reference] +*** xref:mcp:managed/bamboohr.adoc[BambooHR] *** xref:mcp:managed/sql.adoc[SQL] *** xref:mcp:managed/kafka.adoc[Kafka] *** xref:mcp:managed/slack.adoc[Slack] *** xref:mcp:managed/ironclad.adoc[Ironclad] *** xref:mcp:managed/jira.adoc[Jira] *** xref:mcp:managed/metabase.adoc[Metabase] +*** xref:mcp:managed/netsuite.adoc[NetSuite] *** xref:mcp:managed/openapi.adoc[OpenAPI] *** xref:mcp:managed/ramp.adoc[Ramp] *** xref:mcp:managed/workday.adoc[Workday] diff --git a/modules/agents/pages/byoa-register.adoc b/modules/agents/pages/byoa-register.adoc index e41500d..e5c57b0 100644 --- a/modules/agents/pages/byoa-register.adoc +++ b/modules/agents/pages/byoa-register.adoc @@ -176,7 +176,7 @@ The symptom-driven checks in this section cover the three observable parts of th // TODO: replace once standalone-ADP issuer / audience values are confirmed. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/ai-gateway/pages/configure-provider.adoc b/modules/ai-gateway/pages/configure-provider.adoc index 1083639..b68e126 100644 --- a/modules/ai-gateway/pages/configure-provider.adoc +++ b/modules/ai-gateway/pages/configure-provider.adoc @@ -346,7 +346,7 @@ A list/grid view toggle in the top-right switches between table and card layouts // TODO: add screenshots of common error toasts once captured from the live environment. -== Out of scope +== Limitations AI Gateway does not provide these capabilities. For current status, consult the ADP release notes. diff --git a/modules/ai-gateway/pages/overview.adoc b/modules/ai-gateway/pages/overview.adoc index be61e9d..a478997 100644 --- a/modules/ai-gateway/pages/overview.adoc +++ b/modules/ai-gateway/pages/overview.adoc @@ -106,7 +106,7 @@ It is not the right fit when you: * Need routing, failover, or cross-provider load balancing across providers. AI Gateway does not provide these capabilities. [[out-of-scope]] -== Out of scope +== Limitations AI Gateway does not provide these capabilities. For current status, consult the ADP release notes. diff --git a/modules/get-started/pages/byoc-prereqs.adoc b/modules/get-started/pages/byoc-prereqs.adoc index eb00dc5..e51d381 100644 --- a/modules/get-started/pages/byoc-prereqs.adoc +++ b/modules/get-started/pages/byoc-prereqs.adoc @@ -1,5 +1,67 @@ -= ADP BYOC Prerequisites -:description: Requirements for deploying Redpanda ADP in your own cloud environment. += ADP BYOC prerequisites +:description: Requirements for running Redpanda ADP on Redpanda Cloud BYOC clusters on AWS. +:page-topic-type: reference +:personas: platform_admin :page-byoc: true +:learning-objective-1: Identify the AWS BYOC requirements for ADP +:learning-objective-2: Identify the ADP enablement and IAM resource patterns required by Crossplane -// TODO: Add content +// Source: `cloudv2` `terraform/provisioners/aws-redpanda-applications/*.tf`, `adp/manifests/CLAUDE.md`, and BYOC support partials, verified 2026-05-10. +// TODO: Confirm the Redpanda Cloud UI label and status indicator for ADP enablement after an authenticated Cloud walkthrough. + +ADP on BYOC uses Redpanda Cloud BYOC infrastructure on AWS. Use this reference to confirm the requirements before you create ADP resources on a BYOC cluster. + +Use this reference to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} + +== Supported cluster shape + +include::partial$byoc-aws-requirement.adoc[] + +The requirements are: + +* Redpanda Cloud BYOC on AWS +* ADP enabled for the cluster (controlled by `adp_enabled` in the BYOC provisioner source) + +== About Crossplane + +Crossplane is a Kubernetes add-on that manages cloud resources declaratively. Each cloud resource (an IAM role, an RDS instance, a KMS key) is represented as a Kubernetes custom resource, and Crossplane's AWS provider reconciles those resources against your AWS account. + +When ADP is enabled, the BYOC provisioner installs Crossplane in your cluster and attaches an IAM policy that grants it permission to create the cloud resources ADP needs. If your organization restricts IAM in your AWS account, the IAM patterns in the next section are the resource names Crossplane must be allowed to create on Redpanda's behalf. + +== AWS IAM resource patterns + +If your organization customizes BYOC IAM policies, include both AI Gateway and ADP resource name patterns so Crossplane can manage the resources ADP requires. + +[cols="1,3"] +|=== +|Resource kind |Required pattern + +|IAM roles +|`arn:aws:iam:::role/aigw-*` and `arn:aws:iam:::role/adp-*` + +|IAM policies +|`arn:aws:iam:::policy/aigw-*` and `arn:aws:iam:::policy/adp-*` + +|Role policy attachments +|Attachments for roles matching `aigw-*` and `adp-*`, with policy ARNs matching the same AI Gateway and ADP policy patterns. +|=== + +The Crossplane policy also includes permissions for ADP-managed RDS, ElastiCache, KMS, and security-group resources. If your organization customizes the policy, keep those service permissions aligned with the Redpanda-provided BYOC policy. + +== ADP components + +When `adp_enabled` is set, the source provisions ADP components in the cluster, including: + +* The `adp` Kubernetes namespace +* Crossplane resources for ADP infrastructure +* ADP PostgreSQL resources +* AI Gateway +* ADP API + +== Next steps + +* xref:get-started:byoc-quickstart.adoc[Start the ADP BYOC quickstart] +* xref:redpanda-cloud:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[Create a BYOC cluster on AWS] in Redpanda Cloud docs diff --git a/modules/get-started/pages/byoc-quickstart.adoc b/modules/get-started/pages/byoc-quickstart.adoc index 8948e88..a51a1f6 100644 --- a/modules/get-started/pages/byoc-quickstart.adoc +++ b/modules/get-started/pages/byoc-quickstart.adoc @@ -1,5 +1,35 @@ -= ADP BYOC Quickstart -:description: Get started with Redpanda ADP in your own cloud environment. += ADP BYOC quickstart +:description: Start with ADP on a Redpanda Cloud BYOC cluster on AWS. +:page-topic-type: how-to +:personas: platform_admin :page-byoc: true +:learning-objective-1: Check that a BYOC cluster meets the ADP prerequisites +:learning-objective-2: Continue from BYOC cluster setup into ADP provider, MCP, and agent setup -// TODO: Add content +// Source: `cloudv2` BYOC Terraform and Redpanda Cloud BYOC docs source, verified 2026-05-10. +// TODO: Add click-by-click ADP BYOC setup steps after a UI walkthrough. + +This quickstart helps you start ADP on a Redpanda Cloud BYOC cluster on AWS. + +Use this guide to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} + +== Prerequisites + +Review xref:get-started:byoc-prereqs.adoc[ADP BYOC prerequisites]. + +== Create or select a BYOC cluster on AWS + +Use a Redpanda Cloud BYOC cluster on AWS. For the general AWS BYOC cluster creation flow, see xref:redpanda-cloud:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[Create a BYOC cluster on AWS]. + +Before you configure ADP resources, confirm that ADP is enabled for the cluster. The provisioner switch is `adp_enabled`. + +== Continue with ADP setup + +After the BYOC cluster meets the prerequisites, continue with the ADP setup guides: + +. xref:ai-gateway:configure-provider.adoc[Configure your LLM provider] +. xref:mcp:create-server.adoc[Create an MCP server] +. xref:agents:create-agent.adoc[Create a declarative agent] diff --git a/modules/governance/pages/dashboard/overview.adoc b/modules/governance/pages/dashboard/overview.adoc index d89238c..762f872 100644 --- a/modules/governance/pages/dashboard/overview.adoc +++ b/modules/governance/pages/dashboard/overview.adoc @@ -1,16 +1,17 @@ = Read the Governance Overview -:description: See your AI deployment's spending, request volume, token usage, and agent fleet on a single page; filter by provider and model, compare to a previous period, and drill into Spending, Requests, or Tokens views. +:description: Read ADP spend, request, token, agent, and top-user activity from the Governance dashboard. :page-topic-type: how-to :personas: evaluator, platform_admin, app_developer -:learning-objective-1: Identify the four KPI cards, the Spending chart, and the Agents list, and describe what each one surfaces -:learning-objective-2: Filter the Spending chart by provider, model, and cost type, and compare to a previous period -:learning-objective-3: Drill into the Spending, Requests, or Tokens views to investigate further +:learning-objective-1: Read the Total Spend, Requests, and Tokens KPI tabs +:learning-objective-2: Filter governance charts by provider, model, cost type, token type, and user +:learning-objective-3: Use the Agents table and Top users panel to investigate fleet and user-level spend -// TODO: dashboard surface may still be refined; verify chart visuals, filter affordances, and the empty-state copy against the live UI before the next docs pass. +// Source: `cloudv2` `apps/adp-ui/src/routes/governance/index.tsx`, governance components, and `apps/adp-ui/docs/design/0003-governance-v0.md` on `origin/main`, verified 2026-05-10. +// TODO: Capture screenshots and exact empty-state copy after an authenticated walkthrough of the protected ADP UI. -The Governance overview shows your AI deployment's spend, requests, tokens, and agent fleet on a single page. Filter by provider and model, compare current activity against a previous period, and drill into dedicated Spending, Requests, or Tokens views to investigate further. +The Governance dashboard brings AI Gateway usage and agent inventory into one view. Use it to compare spend, request volume, and token volume over a selected time range, then narrow the chart by provider, model, cost type, token type, or user. -After reading this page, you will be able to: +Use this guide to: * [ ] {learning-objective-1} * [ ] {learning-objective-2} @@ -18,196 +19,115 @@ After reading this page, you will be able to: == Prerequisites -* Access to the Agentic Data Plane. -* At least one LLM provider with recent activity, or an empty deployment if you want to see the empty-state behavior. -* The `dataplane_adp_spending_get` permission. The dashboard composes data from `aigw.SpendingService` and the agent registry; without this permission the spend cards and chart are empty. +* Access to the Agentic Data Plane +* The `dataplane_adp_spending_get` permission to read spend, request, and token data +* At least one LLM provider or agent if you want non-empty charts and tables == Open the dashboard -Sign in to ADP and select *Governance* from the sidebar. The overview is the default view. +Sign in to ADP and select *Governance* from the sidebar. The dashboard includes these sections: -// TODO: annotated screenshot of the Governance overview with callouts for the four cards, the Spending chart, and the Agents list. - -The page is laid out top to bottom in three sections: - -. Four summary cards. -. The *Spending* chart with provider, model, and cost-type filters. -. The *Agents* list. - -A *date-range picker* in the top-right scopes everything on the page. +* KPI tabs for *Total Spend*, *Requests*, and *Tokens* +* A metric chart panel +* An *Agents* table +* A *Top users* panel == Set the date range -The date-range picker offers seven preset windows plus a custom calendar: +The date-range control supports these windows: -* *Last 7 days* (default) -* *Last 14 days* -* *Last 30 days* -* *Last 90 days* -* *Month to date* -* *Quarter to date* -* *Year to date* +* Last 24 hours +* Last 7 days (default) +* Last 14 days +* Last 30 days +* Last 90 days +* Month to date +* Quarter to date +* Year to date -For a custom range, pick start and end dates from the two-month calendar. +The app rounds the end of each range up to the next hour. Ranges of 24 hours or less use hourly buckets; longer ranges use daily buckets. -A *Compare to previous period* toggle lives in the same popover. When on, every chart on the page renders the previous comparable window as a dashed-line overlay so you can spot week-over-week or month-over-month trends. Click *Apply* to commit the selection. +== Read the KPI tabs -// TODO: screenshot of the date-range picker open with presets visible. - -== Read the four summary cards - -The cards across the top answer the _how much are you using right now_ question at a glance. +The top of the dashboard shows three KPI tabs, each scoped to the active time range. [cols="1,3"] |=== -|Card |What it shows - -|*TOTAL SPEND* -|Sum of all LLM provider costs in the active window. Displayed in dollars. Sparkline shows daily spend across the window. The _vs previous period_ delta compares to the prior window of equal length. +|Tab |What it shows -|*REQUESTS* -|Total LLM requests routed through AI Gateway in the active window. *View all →* opens the Requests drill-down (see <>). +|Total Spend +|Estimated LLM provider spend in dollars for the selected range -|*TOKENS* -|Total tokens consumed in the active window: input plus output plus cached, summed across all providers and models. *View all →* opens the Tokens drill-down. +|Requests +|LLM requests routed through AI Gateway for the selected range -|*AGENTS* -|Number of agents registered in your deployment. The sub-line breaks the total into running and other states (`9 running · 1 other`). The visual on this card is a bar chart, not a sparkline. +|Tokens +|Input, output, and cached tokens summed together for the selected range |=== -The first three cards (Spend, Requests, Tokens) carry sparklines and a _vs previous period_ delta when *Compare to previous period* is on. The Agents card carries a state breakdown instead. +The tab labels include a compact range suffix, such as `7D`, `30D`, `MTD`, or `YTD`. -NOTE: Provider, model, and user filters scope every metric card on the page, not just the Spending chart. If you select a single provider in the filter popover, the *TOTAL SPEND*, *REQUESTS*, and *TOKENS* cards all narrow to that provider's contribution. Clear the filter to return to the unscoped view. +NOTE: Total spend can lag by up to one hour, and cost values are estimates. Treat Governance spend as operational telemetry, not an invoice. -== Read the Spending chart +== Filter the chart -The *Spending* card shows spend over time, broken out by provider or model. The chart subtitle explains what its lines represent for the active filter combination: - -[quote] -Filter by provider, then drill into models. Cost type narrows what each line sums; hover for the per-day breakdown. - -=== Filter the chart - -The *Filter* button opens a hierarchical popover with three sibling categories: *Provider*, *Model*, *Cost type*. Each category opens a search-filterable, multi-select list. Active filters display as chips above the chart; click a chip's *×* to remove it, or click *Clear* to reset all filters. +The chart supports these filters: [cols="1,3"] |=== |Filter |What it does -|*Provider* -|Multi-select of every LLM provider configured in your dataplane. When 2+ providers are picked, the chart renders a colored line per provider. Chip operator: `is any of`. - -|*Model* -|Multi-select of every model exposed by your providers. When models are picked, the chart drills into per-model lines instead of per-provider. Chip operator: `is any of`. - -|*Cost type* -|Multi-select of *Input*, *Output*, *Cached*. Narrows what each line in the chart sums; the totals strip below the chart still reports all four buckets. Chip operator: `is` for one selection, `is any of` for two or more. -|=== - -NOTE: *Cost type* narrows the chart's lines, not the totals strip. If you select `Cost type | is | Cached`, each line in the chart sums only cached spend; the *INPUT*, *OUTPUT*, and *TOTAL* values in the strip below still reflect the full active Provider/Model selection. - -=== Compare to a previous period - -When *Compare to previous period* is on (in the date-range picker), each line gets a dashed-line counterpart drawn from the same data for the previous comparable window. Hover anywhere on the chart to see a per-day, per-line breakdown with each value's *Previous* sub-row. - -// TODO: screenshot of the spend chart with previous-period overlay and a hover tooltip visible. - -=== Read the cost buckets - -Below the chart, four totals report the active Provider/Model selection: - -[cols="1,3"] -|=== -|Bucket |Meaning +|Provider +|Narrows the chart to one or more LLM providers. -|*TOTAL* -|Sum of input, output, and cached spend. +|Model +|Narrows the chart to one or more models. The UI exposes model filtering after provider filtering. -|*INPUT* -|Cost attributable to prompt tokens, including tool-use inputs. +|Cost type +|Applies to spend charts. Supported cost types are Input, Output, Cached, Cache writes, Reasoning, and Tool use. -|*OUTPUT* -|Cost attributable to completion tokens, including any reasoning tokens for models that emit them (Anthropic 4.x, OpenAI o-series). +|Token type +|Applies to token charts. Supported token types are Input, Output, and Cached. -|*CACHED* -|Cost attributable to cache-read tokens (5-minute or 1-hour prompt caches). Billed at a steep discount versus fresh INPUT. +|User +|Narrows the chart to one identified user. |=== -The dashboard surfaces these as the cost-tracking pipeline records them. Specific multipliers (fast-mode premium, cross-region inference premium, tiered Gemini pricing) are baked into the per-bucket totals automatically; no manual conversion is required. +The chart subtitle summarizes the provider and model behavior: -To override the per-model rate card the pipeline reads from (for negotiated contracts or internal chargeback), see xref:governance:budgets.adoc#override-per-model-pricing[Override per-model pricing]. +[quote] +Filter by provider, then drill into models. Cost type narrows what each line sums; hover for the per-day breakdown. -== Read the Agents list +== Read the Agents table -The Agents card lists every agent in your deployment, managed and BYOA. Columns: +The *Agents* table lists agents registered in the deployment. [cols="1,3"] |=== |Column |What it shows -|*Name* -|Agent resource name. - -|*Type* -|*Redpanda Managed* or *BYOA*. - -|*LLM provider* -|The provider the agent calls, with its provider-type icon. - -|*Model* -|The model identifier the agent uses. -|=== - -A *Filter* button above the table narrows the list by name, type, provider, or model. - -For per-agent state, error count, tool-invocation count, and last-active timestamp, click into the agent's resource page. - -// TODO: per-agent enrichment columns (state, error count, tool-invocation count, last-active timestamp, per-agent spend) are planned for the Agents list itself; remove the per-agent-resource-page workaround sentence once they ship. - -[[drill-down]] -== Drill into a specific view - -The *View all →* link on each KPI card opens a dedicated drill-down page. Filters, model selection, and date range carry over as URL search parameters, so deep-links and back-navigation preserve the current state. +|Name +|Agent display name -[cols="1,3"] -|=== -|View |What it shows - -|*Spending* -|The same chart as the dashboard's Spending card, in a full-page layout. Bottom strip: TOTAL / INPUT / OUTPUT / CACHED. +|Type +|Agent type. The UI labels agents as Redpanda Managed because dataplane v1alpha3 does not distinguish managed agents from BYOA agents in this table. -|*Requests* -|Per-provider and per-model request count over time. Cost-type filter does not apply. Bottom strip: TOTAL REQUESTS. +|LLM provider +|The provider the agent calls -|*Tokens* -|Input + output + cached token volume by provider and model. Each line sums all three token buckets per provider or model. Bottom strip: TOTAL TOKENS. +|Model +|The model identifier the agent uses |=== -A `<` back arrow returns to the dashboard with filter state preserved. +== Read the Top users panel -You can also reach the Spending, Requests, and Tokens drill-downs from a specific provider's detail page. Open *LLM Providers > \{provider}* and click *View all →* on the provider-scoped KPI strip. The drill-down opens with that provider already filtered in. - -== Empty states - -[cols="1,3"] -|=== -|State |What you see - -|*No providers yet* -|The KPI cards show zeroes and a hint that data populates after the first LLM request. The Spending chart is hidden. The Agents list is empty with a link to xref:agents:create-agent.adoc[Create a declarative agent]. - -|*Providers but no traffic* -|The KPI cards show zeroes; the chart is empty with axis labels. Useful for confirming a fresh provider is wired up before traffic flows. - -|*Provider missing in filter* -|If a provider was deleted, its name disappears from the filter; historical lines for the deleted provider continue to render until they fall outside the active window. -|=== +The *Top users* panel shows the highest-spending users in the selected time range. It ranks user-level spend, shows up to five users per page, and includes a heatmap for the ranked users. -// TODO: roadmap items planned for the dashboard but not yet shipped — per-agent enrichment columns (error counts, tool-invocation counts, last-active timestamps, per-agent spend); Agent Network interactive topology graph; aggregated authorization-denials and guardrail-violations feed; kill switch (pause an agent without removing it). Add user-facing pages for each one as they ship; for now, omit from public docs per the project policy not to mark roadmap items in customer prose. +If no user-level spend exists, the panel stays empty until agents send requests on behalf of identified users. -== Investigate further +== Next steps -* xref:observability:transcripts.adoc[Read a transcript]: Full conversation history for an agent run. -* xref:governance:budgets.adoc[Token budgets and limits]: Set spend caps when a provider's cost trends above expectations. -* xref:observability:byoa-telemetry.adoc[BYOA telemetry]: Wire up missing telemetry for BYOA agents that haven't streamed transcripts yet. -* xref:agents:create-agent.adoc[Create a declarative agent]: Add agents to your deployment. +* xref:observability:transcripts.adoc[Read a transcript] +* xref:governance:budgets.adoc[Token budgets and limits] +* xref:observability:byoa-telemetry.adoc[BYOA telemetry] +* xref:agents:create-agent.adoc[Create a declarative agent] diff --git a/modules/integrations/pages/remote-mcp-clients.adoc b/modules/integrations/pages/remote-mcp-clients.adoc index 9f820cc..df8337f 100644 --- a/modules/integrations/pages/remote-mcp-clients.adoc +++ b/modules/integrations/pages/remote-mcp-clients.adoc @@ -244,7 +244,7 @@ Common symptoms and fixes: |The chat client's access token expired and the refresh token also expired (or the OAuth Client secret was rotated). Disconnect the connector and re-add it to mint fresh tokens. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/create-server.adoc b/modules/mcp/pages/create-server.adoc index ccfc9b7..3fc0cc5 100644 --- a/modules/mcp/pages/create-server.adoc +++ b/modules/mcp/pages/create-server.adoc @@ -105,7 +105,7 @@ Both managed and self-managed servers offer the same five authentication modes. |Single shared API key. Provide a `key_ref` (secret reference, `UPPER_SNAKE_CASE`) and an optional `header_name` (defaults to `Authorization`). |*Token passthrough* -|Forward the caller's `Authorization` header to the upstream server as-is. Useful when the upstream already validates upstream tokens. +|Forward the caller's `Authorization` header to the upstream server as-is. Use this mode when the upstream already validates upstream tokens. |*Service-account OAuth* |2-legged OAuth client credentials. One shared upstream identity for every caller. Provide `client_id`, `client_secret_ref`, `token_url`, and any required `scopes`. @@ -143,7 +143,7 @@ Use `rpk ai` for a non-UI path through the same create flow, useful for scriptin [source,bash] ---- # Managed type (Workday example) -rpk ai mcp create workday-hr \ +rpk ai mcp create --name workday-hr \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.workday.v1.WorkdayMCPConfig", "tenant": "acme", @@ -155,16 +155,29 @@ rpk ai mcp create workday-hr \ } }' -# Managed type with user-delegated OAuth (Ramp example) -rpk ai mcp create my-ramp \ - --managed-config '{"@type":"type.googleapis.com/redpanda.mcps.ramp.v1.RampMCPConfig","environment":"production"}' \ - --user-oauth-provider ramp \ - --user-oauth-scopes transactions:read,cards:read,users:read +# Managed type with user-delegated OAuth inside the managed config +# (NetSuite example) +rpk ai mcp create --name netsuite \ + --description "NetSuite ERP with user OAuth" \ + --managed-config '{ + "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig", + "accountId": "1234567_SB1", + "userOauth": { + "providerName": "netsuite", + "requiredScopes": ["rest_webservices"] + } + }' + +# Self-managed server with user-delegated OAuth +rpk ai mcp create --name github-proxy \ + --url https://mcp.example.com/sse \ + --user-oauth-provider github \ + --user-oauth-scopes repo,read:org -# Update a server's user-delegated OAuth scopes -rpk ai mcp update my-ramp \ - --user-oauth-provider ramp \ - --user-oauth-scopes transactions:read,cards:read,cards:write,users:read +# Update a self-managed server's user-delegated OAuth scopes +rpk ai mcp update github-proxy \ + --user-oauth-provider github \ + --user-oauth-scopes repo,read:org,workflow ---- [cols="1,3"] @@ -175,10 +188,10 @@ rpk ai mcp update my-ramp \ |JSON blob carrying the managed type's `_config.proto` shape, including a `@type` URL. |`--user-oauth-provider` -|Name of an OAuth Provider already registered under *OAuth Providers*. See xref:mcp:oauth-providers.adoc[Configure an OAuth Provider]. The principal needs `dataplane_aigateway_oauthprovider_attach` on the named provider (AI-893). +|Self-managed servers only. Name of an OAuth Provider already registered under *OAuth Providers*. See xref:mcp:oauth-providers.adoc[Configure an OAuth Provider]. The principal needs `dataplane_aigateway_oauthprovider_attach` on the named provider (AI-893). Managed servers that support user-delegated OAuth carry their auth shape inside `--managed-config`. |`--user-oauth-scopes` -|Comma-separated scopes the server requires. Provide every scope any tool may need; user re-consent is required if scopes change later. +|Self-managed servers only. Comma-separated scopes the server requires. Provide every scope any tool may need; user re-consent is required if scopes change later. |=== // TODO(rpk-ai): --auth-config does not exist on `rpk ai mcp create` today (verified against cloudv2/apps/rpai/internal/cmd/mcp/cmd.go on 2026-05-05). For non-convenience auth shapes, encode them inside `--managed-config` JSON. Re-add this row if a flag lands later. @@ -215,11 +228,11 @@ The command resolves the gateway URL from your active rpk cloud profile and read // TODO: add screenshots of common error toasts after walking the live cluster. -== Out of scope +== Related topics -The following capabilities are not configured on this page; see the linked content instead. +This page covers creating an MCP server. For other capabilities you may need to configure separately, see: -* *User-delegated OAuth consent flow*: see xref:mcp:user-delegated-oauth.adoc[User-delegated OAuth]. -* *Inspector usage*: see xref:mcp:test-tools.adoc[Test a server's tools]. -* *Multi-server aggregation*: handled by AI Gateway. See xref:ai-gateway:aggregation.adoc[MCP aggregation]. -* *Per-type configuration depth*: see xref:mcp:managed/managed-catalog.adoc[Managed catalog] and the deep-dive pages. +* xref:mcp:user-delegated-oauth.adoc[User-delegated OAuth] for the consent flow your end users will see. +* xref:mcp:test-tools.adoc[Test a server's tools] for using the Inspector tab to call tools, resources, and prompts. +* xref:ai-gateway:aggregation.adoc[MCP aggregation] for fronting many MCP servers behind a single URL with AI Gateway. +* xref:mcp:managed/managed-catalog.adoc[Managed catalog] for per-type configuration depth and deep-dive pages. diff --git a/modules/mcp/pages/managed/bamboohr.adoc b/modules/mcp/pages/managed/bamboohr.adoc new file mode 100644 index 0000000..4408052 --- /dev/null +++ b/modules/mcp/pages/managed/bamboohr.adoc @@ -0,0 +1,108 @@ += BambooHR Managed MCP Server +:description: Let agents read BambooHR employee, time-off, and performance data with each caller's BambooHR OAuth identity. +:page-topic-type: how-to +:personas: app_developer, platform_admin +:learning-objective-1: Configure the BambooHR managed MCP server with a BambooHR subdomain and user-delegated OAuth +:learning-objective-2: Identify the BambooHR tools available to agents +:learning-objective-3: Test BambooHR tool calls with an authorized user's connection + +// Source: `cloudv2` `apps/aigw/docs/bamboohr-mcp.md`, `proto/mcps/redpanda/mcps/bamboohr/v1/*`, and `apps/aigw/internal/mcp/managed/mcps/bamboohr/register_mcp.go` on `origin/main`, verified 2026-05-10. + +The *BambooHR* managed MCP server lets agents read BambooHR employee directory, time-off, and performance data with the calling user's OAuth identity. The BambooHR configuration stores only the company subdomain. OAuth credentials and user tokens come from the OAuth Provider and token vault. + +Use this guide to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== What this MCP server does + +Use BambooHR when an agent needs HR context from BambooHR without sharing one upstream API key across every caller. Each caller authorizes with BambooHR, and tool calls run with the BambooHR permissions available to that caller. + +[cols="1,3"] +|=== +|Tool |What it does + +|`get_employee` +|Fetches a single employee by ID. Use employee ID `0` to return the authenticated user's own record. You can pass a comma-separated `fields` list, or leave it empty to return all fields the caller can access. + +|`get_employee_directory` +|Lists all employee directory entries visible to the authenticated user. + +|`get_time_off_requests` +|Queries time-off requests by date range. You can filter by employee ID, status, or time-off type. Supported statuses are `approved`, `denied`, `superceded`, `requested`, and `canceled`. + +|`whos_out` +|Returns absences and holidays in a date range. If you omit dates, the server starts with today and ends 14 days later. + +|`get_performance_feedback` +|Returns peer or manager feedback for an employee. You can filter by `completed`, `pending`, or all feedback. +|=== + +== Prerequisites + +* Access to the Agentic Data Plane. +* A BambooHR workspace where you can create an OAuth 2.0 application. +* A BambooHR OAuth Provider in ADP. BambooHR OAuth authorize and token endpoints include your company subdomain. +* A BambooHR company subdomain, such as `mycompany` for `mycompany.bamboohr.com`. The managed config accepts letters, numbers, and hyphens. +* BambooHR users with the permissions required to read the employee, time-off, or performance data your agent needs. + +// TODO: Confirm the exact ADP UI field labels for attaching user-delegated OAuth to managed BambooHR after an authenticated UI walkthrough. +// TODO: Add a CLI example only after confirming how `rpk ai` sets MCPServer `auth_config.user_oauth` for managed types that do not carry auth inside the managed config. + +== Configure BambooHR OAuth + +In BambooHR, create an OAuth 2.0 application in the BambooHR developer settings. Use the OAuth callback URL for your AI Gateway deployment. + +Register a BambooHR OAuth Provider in ADP with tenant-specific endpoints: + +[source,text] +---- +Authorization endpoint: https://api.bamboohr.com/api/gateway.php//v1/oauth2/authorize +Token endpoint: https://api.bamboohr.com/api/gateway.php//v1/oauth2/token +---- + +Store the BambooHR client secret in the ADP secret store, then reference that secret from the OAuth Provider. + +== Create the managed MCP server + +Create a managed MCP server with the BambooHR type. Set the `subdomain` field and attach the BambooHR OAuth Provider as user-delegated OAuth on the MCP server. + +The BambooHR managed config contains only the company subdomain: + +[source,json] +---- +{ + "@type": "type.googleapis.com/redpanda.mcps.bamboohr.v1.BambooHRMCPConfig", + "subdomain": "mycompany" +} +---- + +== Authorize and test + +Before a caller can use BambooHR tools, the caller must authorize the BambooHR OAuth Provider. After authorization, Redpanda stores the user's access token in the token vault and subsequent tool calls use that token automatically. + +Test the server in the Inspector before you connect it to an agent. Start with `get_employee_directory` or `get_employee` with employee ID `0`, because both calls confirm that the user's OAuth connection resolves and BambooHR returns data visible to that user. + +== Troubleshooting + +[cols="1,3"] +|=== +|Symptom |What to check + +|Tool calls return permission errors +|Confirm the BambooHR user can access the requested HR data. Restricted BambooHR roles can return permission errors, especially for performance data. + +|OAuth succeeds, but tool calls fail +|Confirm the OAuth Provider endpoints use the same BambooHR subdomain as the MCP server configuration. + +|The server cannot find the BambooHR company +|Confirm `subdomain` contains only the part before `.bamboohr.com`, such as `mycompany`. +|=== + +== Next steps + +* xref:mcp:user-delegated-oauth.adoc[Configure user-delegated OAuth] +* xref:mcp:test-tools.adoc[Test a server's tools] +* xref:agents:create-agent.adoc[Create a declarative agent] that uses the BambooHR server diff --git a/modules/mcp/pages/managed/ironclad.adoc b/modules/mcp/pages/managed/ironclad.adoc index 54dd2b2..b3cc1c3 100644 --- a/modules/mcp/pages/managed/ironclad.adoc +++ b/modules/mcp/pages/managed/ironclad.adoc @@ -45,7 +45,7 @@ Set up the OAuth app on Ironclad and the matching OAuth Provider in ADP: + * *Authorization endpoint*: `\https://na1.ironcladapp.com/oauth/authorize` (use `eu1` for EU-hosted accounts; `demo` for sandbox) * *Token endpoint*: `\https://na1.ironcladapp.com/oauth/token` (adjust region accordingly) -* The Client ID and a secret-store reference for the Client Secret. +* The Client ID and a secret-store reference for the Client Secret == Configure @@ -78,7 +78,7 @@ Create a new Ironclad MCP server in the ADP UI: [source,bash] ---- -rpk ai mcp create my-ironclad \ +rpk ai mcp create --name my-ironclad \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.ironclad.v1.IroncladMCPConfig", "region": "IRONCLAD_REGION_NA" @@ -150,7 +150,7 @@ Common symptoms and fixes: |Run `list_workflow_schemas` first to get valid IDs for your tenant. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/managed/jira.adoc b/modules/mcp/pages/managed/jira.adoc index 45b895b..62f4eb9 100644 --- a/modules/mcp/pages/managed/jira.adoc +++ b/modules/mcp/pages/managed/jira.adoc @@ -109,8 +109,8 @@ For agents that need both read and write capabilities, define the server's `requ // TODO: capture more Atlassian-specific errors during the live walkthrough. -== Out of scope +== Limitations -* *Atlassian app management* — the OAuth app and its callback URLs are managed in `developer.atlassian.com`, not in ADP. -* *Jira Server / Data Center* (self-hosted) — this MCP type targets Atlassian Cloud. Self-hosted Jira may need a self-managed MCP server instead. See xref:../register-remote.adoc[]. -* *Confluence access* — separate scope namespace; not exposed by this MCP server. +* *Atlassian app management*: the OAuth app and its callback URLs are managed in `developer.atlassian.com`, not in ADP. +* *Jira Server / Data Center* (self-hosted): this MCP type targets Atlassian Cloud. Self-hosted Jira may need a self-managed MCP server instead. See xref:../register-remote.adoc[Register a self-managed MCP server]. +* *Confluence access*: separate scope namespace; not exposed by this MCP server. diff --git a/modules/mcp/pages/managed/kafka.adoc b/modules/mcp/pages/managed/kafka.adoc index 3847000..2011ee9 100644 --- a/modules/mcp/pages/managed/kafka.adoc +++ b/modules/mcp/pages/managed/kafka.adoc @@ -109,8 +109,8 @@ Once the Kafka server is created, point an agent at the *API URL* on the server' // TODO: gather more Kafka failure modes from `adp-production` walkthroughs. -== Out of scope +== Limitations -* *Kafka administration* (creating topics, managing ACLs) — this server is read/produce/consume-focused. For administration, use rpk or your broker's admin API. -* *Schema registry* — not exposed by this MCP server. -* *Streaming joins / processing* — for stream processing, use Redpanda Connect. +* *Kafka administration* (creating topics, managing ACLs): this server is read/produce/consume-focused. For administration, use rpk or your broker's admin API. +* *Schema registry*: not exposed by this MCP server. +* *Streaming joins or processing*: for stream processing, use Redpanda Connect. diff --git a/modules/mcp/pages/managed/managed-catalog.adoc b/modules/mcp/pages/managed/managed-catalog.adoc index 4da2ec2..75b3f75 100644 --- a/modules/mcp/pages/managed/managed-catalog.adoc +++ b/modules/mcp/pages/managed/managed-catalog.adoc @@ -3,12 +3,10 @@ :page-topic-type: reference :personas: app_developer, platform_admin -Managed MCP servers are in-process implementations Redpanda hosts for you. Each type has a fixed set of glossterm:tool[,tools] and a type-specific configuration schema. To create one, open *MCP Servers > Create Server* in the ADP UI and pick the type from the marketplace picker. See xref:create-server.adoc[Create an MCP Server] for the full create flow. +Managed MCP servers are in-process implementations Redpanda hosts for you. Each type has a fixed set of glossterm:tool[,tools] and a type-specific configuration schema. To create one, open *MCP Servers > Create Server* in the ADP UI and pick the type from the marketplace picker. See xref:mcp:create-server.adoc[Create an MCP Server] for the full create flow. -// TODO(review-before-publish): "currently registered" softens the claim that the catalog can change. Confirm whether to drop "currently" (treat the list as a static snapshot at publish time) or replace with a versioning note ("as of release X.Y"). -This catalog lists every managed type currently registered, grouped by `ManagedMCPCategory`. Display names and descriptions are lifted verbatim from the type registrations in `cloudv2`. - -// TODO: confirm the registered list at GA — counts and category assignments are subject to last-minute adds/renames. Re-verify against `apps/aigw/internal/mcp/managed/mcps/*/register_mcp.go`. +// Source: `cloudv2` `apps/aigw/internal/mcp/managed/defaults.go` and managed type registration files on `origin/main`, verified 2026-05-10. +This catalog lists the 36 managed MCP server types Redpanda registers by default, grouped by category. == Choosing managed vs. self-managed @@ -26,10 +24,10 @@ This catalog lists every managed type currently registered, grouped by `ManagedM |The fixed tool set of the managed type covers your use case. |Do you need per-user identities at the upstream? -|The managed type supports user-delegated OAuth (Slack, Jira, Google types do; SQL/Kafka don't). +|The managed type supports user-delegated OAuth for that system. |=== -If any of these answers are "no," prefer xref:register-remote.adoc[a self-managed server] instead. +If any of these answers are "no," prefer xref:mcp:register-remote.adoc[a self-managed server] instead. == AI @@ -39,15 +37,15 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |*AWS Bedrock* |Invoke foundation models (Claude, Llama, Titan) on AWS Bedrock. -|— +| |*Cohere* -|Generate embeddings and chat completions via the Cohere API. -|— +|Generate embeddings and chat completions with the Cohere API. +| |*OpenAI* -|Chat completions, embeddings, and tools via the OpenAI API. -|— +|Chat completions, embeddings, and tools with the OpenAI API. +| |=== == AWS @@ -58,11 +56,11 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |*AWS SNS* |Publish and manage topics on AWS Simple Notification Service. -|— +| |*AWS SQS* |Send, receive, and manage messages on AWS Simple Queue Service. -|— +| |=== == Communication @@ -73,23 +71,23 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |*Discord* |Post messages, read channels, and manage servers on Discord. -|— +| |*GitHub (Read)* |Read-only access to GitHub repositories, pull requests, commits, and code. -|— +| |*Jira* |Manage Jira issues, projects, and workflows. -|xref:managed/jira.adoc[See the deep-dive →] +|xref:mcp:managed/jira.adoc[See the deep-dive] |*Slack* |Post messages and read channels on Slack. -|xref:managed/slack.adoc[See the deep-dive →] +|xref:mcp:managed/slack.adoc[See the deep-dive] |*Zendesk* |Search and manage Zendesk Support tickets, users, and Help Center articles. -|xref:managed/zendesk.adoc[See the deep-dive →] +|xref:mcp:managed/zendesk.adoc[See the deep-dive] |=== == Database @@ -100,23 +98,27 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |*Elasticsearch* |Query and index documents in an Elasticsearch cluster. -|— +| + +|*Metabase* +|Search tables and metrics, run queries, and inspect saved questions in Metabase. +|xref:mcp:managed/metabase.adoc[See the deep-dive] |*MongoDB* |Query collections and documents in MongoDB. -|— +| |*Qdrant* |Vector search over a Qdrant collection. -|— +| |*Redis* |Read, write, and query keys in Redis. -|— +| |*SQL* -|Query SQL databases (Postgres, MySQL, ClickHouse, MSSQL, SQLite) via MCP. -|xref:managed/sql.adoc[See the deep-dive →] +|Query SQL databases (Postgres, MySQL, ClickHouse, MSSQL, SQLite) with MCP. +|xref:mcp:managed/sql.adoc[See the deep-dive] |=== == Google @@ -127,15 +129,15 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |*GCP Pub/Sub* |Publish and subscribe to topics on Google Cloud Pub/Sub. -|— +| |*Google Calendar* |Read and manage Google Calendar events and schedules. -|— +| |*Google Drive* |Read and search files in Google Drive. -|— +| |=== == Streaming @@ -146,11 +148,11 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |*Kafka* |Produce, consume, and inspect topics on Kafka or Redpanda brokers. -|xref:managed/kafka.adoc[See the deep-dive →] +|xref:mcp:managed/kafka.adoc[See the deep-dive] |*NATS* |Publish and subscribe on NATS and NATS JetStream. -|— +| |=== == Utility @@ -159,57 +161,69 @@ If any of these answers are "no," prefer xref:register-remote.adoc[a self-manage |=== |Display name |Description |Deep dive +|*Azure AD* +|Manage Azure Active Directory users and groups with Microsoft Graph API. +| + |*BambooHR* |Access employee directory, time-off, and performance data from BambooHR. -|— +|xref:mcp:managed/bamboohr.adoc[See the deep-dive] |*BILL (bill.com)* |Manage accounts-payable bills, vendors, AR invoices, payments, and customers in BILL. -|— +| |*DocuSign* |Send, track, and manage DocuSign signing envelopes. -|— +| |*Greenhouse* |Manage jobs, candidates, and applications in Greenhouse ATS. -|— +| |*Ironclad* |Read and manage contracts in Ironclad CLM. -|xref:managed/ironclad.adoc[See the deep-dive →] +|xref:mcp:managed/ironclad.adoc[See the deep-dive] + +|*Morningstar Portfolio Analytics* +|Run X-Ray, performance, risk-score, hypothetical, and ESG analytics on caller-supplied portfolios with Morningstar Direct Web Services. +| + +|*Morningstar Securities* +|Search, retrieve, screen, and pull research on funds and equities with the Morningstar Direct Web Services Investment Analysis API. +| + +|*NetSuite* +|Query Oracle NetSuite records and run SuiteQL with the SuiteTalk REST API. +|xref:mcp:managed/netsuite.adoc[See the deep-dive] |*Okta* |Manage Okta users and groups. -|— - -|*Metabase* -|Search, browse, and query a Metabase analytics instance through its semantic layer (tables, metrics) plus SQL escape hatches. -|xref:managed/metabase.adoc[See the deep-dive →] +| |*OpenAPI* |Expose any OpenAPI/Swagger HTTP API as MCP tools. -|xref:managed/openapi.adoc[See the deep-dive →] +|xref:mcp:managed/openapi.adoc[See the deep-dive] |*Ramp* |Manage Ramp corporate cards, transactions, spend limits, and reimbursements. -|xref:managed/ramp.adoc[See the deep-dive →] +|xref:mcp:managed/ramp.adoc[See the deep-dive] |*Salesforce* |Query, create, update, and delete Salesforce CRM records using SOQL and the REST API. -|— +| |*Text Chunker* |Split and chunk text for RAG and LLM ingestion pipelines. -|— +| |*Workday* -|Drive Workday Human Resources business processes via SOAP. -|xref:managed/workday.adoc[See the deep-dive →] +|Drive Workday Human Resources business processes with SOAP. +|xref:mcp:managed/workday.adoc[See the deep-dive] |=== -== Where to go next +== Next steps -* xref:create-server.adoc[Create an MCP server] using the marketplace picker. -* xref:test-tools.adoc[Test tools with the Inspector] before pointing an agent at the server. -* xref:user-delegated-oauth.adoc[Configure user-delegated OAuth] for types that need per-user upstream identities. +* xref:mcp:create-server.adoc[Create an MCP server] using the marketplace picker +* xref:mcp:test-tools.adoc[Test tools with the Inspector] before pointing an agent at the server +* xref:mcp:user-delegated-oauth.adoc[Configure user-delegated OAuth] for types that need per-user upstream identities diff --git a/modules/mcp/pages/managed/metabase.adoc b/modules/mcp/pages/managed/metabase.adoc index 83ca2b8..ec9d4ab 100644 --- a/modules/mcp/pages/managed/metabase.adoc +++ b/modules/mcp/pages/managed/metabase.adoc @@ -91,7 +91,7 @@ Run `rpk ai mcp create` with the Metabase managed-config payload: [source,bash] ---- -rpk ai mcp create metabase --managed-config '{ +rpk ai mcp create --name metabase --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.metabase.v1.MetabaseMCPConfig", "base_url": "https://metabase.mycompany.com", "api_key": { @@ -281,7 +281,7 @@ Common symptoms and fixes: |Confirm the relevant metric exists and has queryable dimensions. The agent prefers metrics when `search` or `get_table` surfaces them. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/managed/netsuite.adoc b/modules/mcp/pages/managed/netsuite.adoc new file mode 100644 index 0000000..817773c --- /dev/null +++ b/modules/mcp/pages/managed/netsuite.adoc @@ -0,0 +1,145 @@ += NetSuite Managed MCP Server +:description: Let agents read NetSuite records and run SuiteQL with each caller's NetSuite OAuth identity. +:page-topic-type: how-to +:personas: app_developer, platform_admin +:learning-objective-1: Configure the NetSuite managed MCP server with account ID and user-delegated OAuth +:learning-objective-2: Identify the NetSuite read-only tools available to agents +:learning-objective-3: Test NetSuite tool calls with an authorized user's connection + +// Source: `cloudv2` `apps/aigw/docs/netsuite-mcp.md`, `proto/mcps/redpanda/mcps/netsuite/v1/*`, and `apps/aigw/internal/mcp/managed/mcps/netsuite/register_mcp.go` on `origin/main`, verified 2026-05-10. + +The *NetSuite* managed MCP server lets agents query Oracle NetSuite records and run SuiteQL with the calling user's OAuth identity. The server wraps SuiteTalk REST APIs and exposes read-only tools for records, customers, sales orders, and items. + +Use this guide to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== What this MCP server does + +Use NetSuite when an agent needs ERP, finance, or accounting context from records that a NetSuite user can already read. Every tool is read-only. + +[cols="1,3"] +|=== +|Tool |What it does + +|`suite_ql_query` +|Runs a SuiteQL query and returns rows as JSON. Use this tool for joins, aggregates, and cross-record analysis. + +|`get_record` +|Fetches one record by record type and internal ID. You can expand sub-resources, such as line items and addresses. + +|`list_records` +|Lists records of a type with optional NetSuite filter expression and paging. Use typed helpers when they fit. + +|`get_customer` +|Fetches a customer record by internal ID. + +|`list_customers` +|Lists customers with optional company name, email, modified-since, inactive, and paging filters. + +|`list_sales_orders` +|Lists sales orders with optional customer ID, date range, status, modified-since, and paging filters. + +|`search_items` +|Searches inventory and service items by SKU, display name, item type, inactive flag, and paging filters. +|=== + +The managed server does not expose write tools, saved-search execution, or report execution. + +== Prerequisites + +* Access to the Agentic Data Plane. +* A NetSuite Integration Record that uses OAuth 2.0 Authorization Code grant. +* A NetSuite OAuth Provider in ADP for the same account. +* Your NetSuite account ID. Production accounts use a numeric ID such as `1234567`. Sandbox accounts include a suffix such as `1234567_SB1`; release-preview accounts can use a suffix such as `1234567_RP1`. +* NetSuite users with the *REST Web Services* permission on at least one role. + +// TODO: Confirm the exact ADP UI field labels for NetSuite OAuth Provider creation after an authenticated UI walkthrough. + +== Configure NetSuite OAuth + +In NetSuite, create an Integration Record with OAuth 2.0 enabled. Set the redirect URI to the OAuth callback URL for your AI Gateway deployment. Select the *REST Web Services* scope. + +Find your account ID under *Setup > Company > Company Information > ACCOUNT ID*. The managed server normalizes underscores to hyphens when it builds the SuiteTalk host. + +Register a NetSuite OAuth Provider in ADP with account-scoped endpoints: + +[source,text] +---- +Authorization endpoint: https://.app.netsuite.com/app/login/oauth2/authorize.nl +Token endpoint: https://.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token +Scopes: rest_webservices +---- + +Store the NetSuite client secret in the ADP secret store, then reference that secret from the OAuth Provider. + +== Create the managed MCP server + +Create a managed MCP server with the NetSuite type. NetSuite authentication is part of the managed config, so include `userOauth` inside the JSON. + +[source,json] +---- +{ + "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig", + "accountId": "1234567_SB1", + "userOauth": { + "providerName": "netsuite", + "requiredScopes": ["rest_webservices"] + } +} +---- + +For a non-UI path, use `rpk ai mcp create` with `--managed-config`. The top-level `--user-oauth-provider` and `--user-oauth-scopes` flags apply to self-managed servers only. + +[source,bash] +---- +rpk ai mcp create --name netsuite \ + --description "NetSuite ERP with user OAuth" \ + --managed-config '{ + "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig", + "accountId": "1234567_SB1", + "userOauth": { + "providerName": "netsuite", + "requiredScopes": ["rest_webservices"] + } + }' +---- + +== Authorize and test + +Before a caller can use NetSuite tools, the caller must authorize the NetSuite OAuth Provider. After authorization, Redpanda stores the user's access token in the token vault and subsequent tool calls use that token automatically. + +Test the server in the Inspector before you connect it to an agent. Start with a narrow `suite_ql_query`, `get_customer`, or `list_customers` call to confirm that NetSuite returns records visible to the authorized user. + +== NetSuite query notes + +NetSuite record filters use NetSuite-specific forms: + +* Use `CONTAIN` for substring filters, not `CONTAINS`. +* Use `M/D/YYYY` date literals for REST collection filters. +* Match reference fields by internal ID. For example, sales-order customer filters use `entity ANY_OF [12345]`. +* Use NetSuite status IDs such as `_pendingFulfillment` for sales-order status filters, not display labels. + +== Troubleshooting + +[cols="1,3"] +|=== +|Symptom |What to check + +|Tool calls return `403` +|Confirm the authorizing NetSuite user has the *REST Web Services* permission. + +|OAuth succeeds, but tool calls fail +|Confirm the OAuth Provider endpoints and the MCP server `accountId` refer to the same NetSuite account. + +|A sales-order status filter returns no rows +|Use the NetSuite internal status ID, such as `_pendingFulfillment`, instead of the display label. +|=== + +== Next steps + +* xref:mcp:user-delegated-oauth.adoc[Configure user-delegated OAuth] +* xref:mcp:test-tools.adoc[Test a server's tools] +* xref:agents:create-agent.adoc[Create a declarative agent] that uses the NetSuite server diff --git a/modules/mcp/pages/managed/openapi.adoc b/modules/mcp/pages/managed/openapi.adoc index 2475073..e054465 100644 --- a/modules/mcp/pages/managed/openapi.adoc +++ b/modules/mcp/pages/managed/openapi.adoc @@ -107,8 +107,8 @@ Once tools generate cleanly, point an agent at the *API URL* on the server's det // TODO: capture more spec-specific failure modes during the live walkthrough. -== Out of scope +== Limitations -* *Custom tool logic* — the OpenAPI type is purely a spec-to-tools generator. For business logic on top of the API, use a self-managed MCP server (xref:../register-remote.adoc[]). -* *GraphQL APIs* — OpenAPI doesn't describe GraphQL; for GraphQL APIs, use a self-managed server. -* *gRPC services* — same. +* *Custom tool logic*: the OpenAPI type is purely a spec-to-tools generator. For business logic on top of the API, use a xref:../register-remote.adoc[self-managed MCP server]. +* *GraphQL APIs*: OpenAPI doesn't describe GraphQL. For GraphQL APIs, use a self-managed server. +* *gRPC services*: same as GraphQL — use a self-managed server. diff --git a/modules/mcp/pages/managed/ramp.adoc b/modules/mcp/pages/managed/ramp.adoc index 596f93f..0516888 100644 --- a/modules/mcp/pages/managed/ramp.adoc +++ b/modules/mcp/pages/managed/ramp.adoc @@ -51,7 +51,7 @@ Set up the OAuth app on Ramp and the matching OAuth Provider in ADP: + * *Authorization endpoint*: `\https://app.ramp.com/v1/authorize` * *Token endpoint*: `\https://api.ramp.com/developer/v1/token` -* The Client ID and a secret-store reference for the Client Secret. +* The Client ID and a secret-store reference for the Client Secret == Configure @@ -84,7 +84,7 @@ Create a new Ramp MCP server in the ADP UI: [source,bash] ---- -rpk ai mcp create my-ramp \ +rpk ai mcp create --name my-ramp \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.ramp.v1.RampMCPConfig", "environment": "production" @@ -206,7 +206,7 @@ Common symptoms and fixes: |The calling user's Ramp role doesn't grant the action. Ramp's role-based access control runs end-to-end: per-user OAuth means each user only sees what their Ramp account permits. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/managed/slack.adoc b/modules/mcp/pages/managed/slack.adoc index 037385d..388d26c 100644 --- a/modules/mcp/pages/managed/slack.adoc +++ b/modules/mcp/pages/managed/slack.adoc @@ -101,7 +101,7 @@ Common symptoms and fixes: // TODO: capture more Slack-specific errors during the live walkthrough. -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/managed/sql.adoc b/modules/mcp/pages/managed/sql.adoc index 869bd3c..da7c103 100644 --- a/modules/mcp/pages/managed/sql.adoc +++ b/modules/mcp/pages/managed/sql.adoc @@ -104,7 +104,7 @@ Once the SQL server is created, point an agent at the *API URL* on the server's // TODO: gather more failure modes once we walk SQL on `adp-production`. -== Out of scope +== Limitations -* *Schema migrations* — this server is read/query-focused; running DDL is not the intended use. -* *Per-user database identities* — see <>. +* *Schema migrations*: this server is read/query-focused; running DDL is not the intended use. +* *Per-user database identities*: see <>. diff --git a/modules/mcp/pages/managed/workday.adoc b/modules/mcp/pages/managed/workday.adoc index a2d7ed5..15c1289 100644 --- a/modules/mcp/pages/managed/workday.adoc +++ b/modules/mcp/pages/managed/workday.adoc @@ -34,8 +34,8 @@ Authentication is one ISU per MCP instance, not per end-user. Customers that nee Before you create the server, make sure you have: -* A Workday tenant where you can create an Integration System User and register an API client. -* Admin access to *Workday > Create Integration System User* and *Workday > Register API Client for Integrations*. +* A Workday tenant where you can create an Integration System User and register an API client +* Admin access to *Workday > Create Integration System User* and *Workday > Register API Client for Integrations* * Two ADP secret-store entries: + * `WORKDAY_PASSWORD`: The ISU password. @@ -94,7 +94,7 @@ Create a new Workday MCP server in the ADP UI: [source,bash] ---- -rpk ai mcp create workday-hr --managed-config '{ +rpk ai mcp create --name workday-hr --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.workday.v1.WorkdayMCPConfig", "tenant": "acme", "host": "wd2-impl-services1.workday.com", @@ -187,7 +187,7 @@ Common symptoms and fixes: |The `worker_id` plus `worker_id_type` doesn't resolve. Verify the type (`Employee_ID`, `Workday_ID`, `Contingent_Worker_ID`) and the value. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/managed/zendesk.adoc b/modules/mcp/pages/managed/zendesk.adoc index 630ef60..4247802 100644 --- a/modules/mcp/pages/managed/zendesk.adoc +++ b/modules/mcp/pages/managed/zendesk.adoc @@ -99,7 +99,7 @@ API-token mode:: + [source,bash] ---- -rpk ai mcp create acme-zendesk --managed-config '{ +rpk ai mcp create --name acme-zendesk --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig", "subdomain": "acme", "basic_auth": { @@ -113,7 +113,7 @@ User-OAuth mode:: + [source,bash] ---- -rpk ai mcp create acme-zendesk-oauth \ +rpk ai mcp create --name acme-zendesk-oauth \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig", "subdomain": "acme" @@ -264,7 +264,7 @@ Common symptoms and fixes: |Cannot happen: the handler enforces a `type:ticket` qualifier and post-filters results. If you see something unexpected, file an issue. |=== -== Out of scope +== Limitations This page does not cover: diff --git a/modules/mcp/pages/overview.adoc b/modules/mcp/pages/overview.adoc index aef3c26..f70a007 100644 --- a/modules/mcp/pages/overview.adoc +++ b/modules/mcp/pages/overview.adoc @@ -18,7 +18,8 @@ Redpanda offers two kinds of MCP server backends: |You already run an MCP server somewhere and want Redpanda to proxy it for authentication, observability, aggregation, and agent access. Redpanda fronts your server with a managed URL and resolves auth at the gateway. |=== -// TODO: confirm exact count of managed types at GA — currently 27 in the registry. +// Source: `cloudv2` `apps/aigw/internal/mcp/managed/defaults.go` on `origin/main`, verified 2026-05-10. +The default registry contains 36 managed MCP server types. See xref:mcp:managed/managed-catalog.adoc[Managed catalog] for the verified list. == When to use each @@ -53,23 +54,23 @@ The Agentic Data Plane UI has four top-level areas: * *LLM Providers*: OpenAI, Anthropic, Bedrock, Gemini, OpenAI-compatible endpoints. See xref:ai-gateway:configure-provider.adoc[Configure your LLM provider]. * *MCP Servers*: You are here. Both managed and self-managed servers live in this list. -* *OAuth Providers*: Reusable OAuth provider definitions used by user-delegated MCP auth (and elsewhere). See xref:user-delegated-oauth.adoc[User-delegated OAuth]. -* *My Connections*: Per-user OAuth connections for user-delegated MCP servers. See xref:user-delegated-oauth.adoc[User-delegated OAuth]. +* *OAuth Providers*: Reusable OAuth provider definitions used by user-delegated MCP auth (and elsewhere). See xref:mcp:user-delegated-oauth.adoc[User-delegated OAuth]. +* *My Connections*: Per-user OAuth connections for user-delegated MCP servers. See xref:mcp:user-delegated-oauth.adoc[User-delegated OAuth]. // TODO: screenshot of the four-area sidebar on adp-production once standalone-ADP wording is final. == Key capabilities -* *Tool discovery*: After you create or register a server, Redpanda performs a live `tools/list` against it and populates the server's detail page so you can see what tools agents will see. +* *Tool discovery*: After you create or register a server, Redpanda performs a live `tools/list` against it and populates the server's detail page so you can see which tools are visible to agents. * *Service-account and user-delegated auth*: Pick a single shared upstream identity for all callers, or have each end-user authenticate against the upstream system with their own credentials. * *Code mode*: Optionally expose `{name}_search` and `{name}_execute` helpers so an agent can discover and orchestrate tools through generated Python or JavaScript instead of calling them one at a time. -* *Inspector*: Test each tool, resource, and prompt directly from the ADP UI before pointing an agent at the server. See xref:test-tools.adoc[Test a server's tools]. +* *Inspector*: Test each tool, resource, and prompt directly from the ADP UI before pointing an agent at the server. See xref:mcp:test-tools.adoc[Test a server's tools]. * *Aggregation*: Connect your agent to a single MCP URL and have Redpanda fan out across multiple registered MCP servers. See xref:ai-gateway:aggregation.adoc[MCP aggregation]. == Next steps -. *Create your first MCP server.* xref:create-server.adoc[Create an MCP Server] walks through the marketplace picker, the managed and self-managed flows, every authentication mode, and code mode. -. *Test what you built.* xref:test-tools.adoc[Test a server's tools] uses the Inspector tab to call tools, resources, and prompts live. -. *Wire up user-delegated OAuth* if your users should authenticate against the upstream system with their own credentials. See xref:user-delegated-oauth.adoc[User-delegated OAuth]. -. *Register an existing server* you already run yourself. See xref:register-remote.adoc[Register a self-managed server]. -. *Browse the managed catalog* for the full list of types, their categories, and per-type configuration links. See xref:managed/managed-catalog.adoc[Managed catalog]. +. *Create your first MCP server.* xref:mcp:create-server.adoc[Create an MCP Server] walks through the marketplace picker, the managed and self-managed flows, every authentication mode, and code mode. +. *Test what you built.* xref:mcp:test-tools.adoc[Test a server's tools] uses the Inspector tab to call tools, resources, and prompts live. +. *Wire up user-delegated OAuth* when your users authenticate against the upstream system with their own credentials. See xref:mcp:user-delegated-oauth.adoc[User-delegated OAuth]. +. *Register an existing server* you already run yourself. See xref:mcp:register-remote.adoc[Register a self-managed server]. +. *Browse the managed catalog* for the full list of types, their categories, and per-type configuration links. See xref:mcp:managed/managed-catalog.adoc[Managed catalog]. diff --git a/modules/mcp/pages/register-remote.adoc b/modules/mcp/pages/register-remote.adoc index b867c02..2a20056 100644 --- a/modules/mcp/pages/register-remote.adoc +++ b/modules/mcp/pages/register-remote.adoc @@ -6,7 +6,7 @@ :learning-objective-2: Pick the right transport (SSE vs. Streamable HTTP) and authentication mode :learning-objective-3: Confirm tool discovery completed and the server is reachable through its proxy URL -Register your existing MCP server with Redpanda to add authentication, observability, and agent aggregation without changing your server's code. This guide covers the self-managed path from xref:create-server.adoc[Create an MCP Server] in depth — choose this when you already run a server and want Redpanda to proxy it. +Register your existing MCP server with Redpanda to add authentication, observability, and agent aggregation without changing your server's code. This guide covers the self-managed path from xref:create-server.adoc[Create an MCP Server] in depth. Choose this when you already run a server and want Redpanda to proxy it. After completing this guide, you will be able to: @@ -22,7 +22,7 @@ Choose self-managed registration when: * You need custom tool logic that no managed type provides. * You want a unified MCP URL (and Inspector / observability / agent access) across servers without standing up your own gateway. -If you don't already run a server, prefer a managed type — see xref:managed/managed-catalog.adoc[Managed catalog] for the catalog. +If you don't already run a server, prefer a managed type. See xref:managed/managed-catalog.adoc[Managed catalog] for the catalog. == Prerequisites @@ -30,7 +30,7 @@ If you don't already run a server, prefer a managed type — see xref:managed/ma + // TODO: confirm network reachability requirements (egress / VPC peering / public endpoint) once the standalone ADP product surface ships. * The endpoint URL. `http://` is allowed for everything except user-delegated OAuth, which requires `https://` (proto rule `remote_mcp.user_oauth_requires_https`). -* Knowledge of which transport the server speaks — SSE or Streamable HTTP. If you don't know, see <>. +* Knowledge of which transport the server speaks (SSE or Streamable HTTP). If you don't know, see <>. * If using static-key or service-account-OAuth: secrets pre-created in the ADP secret store, `UPPER_SNAKE_CASE` (proto regex `^[A-Z][A-Z0-9_]*$`). * If using user-delegated OAuth: an OAuth Provider already configured. See xref:user-delegated-oauth.adoc[User-delegated OAuth]. @@ -40,7 +40,7 @@ If you don't already run a server, prefer a managed type — see xref:managed/ma . In the marketplace picker, choose *Remote (Proxied)*. + // TODO: screenshot of the marketplace picker with Remote (Proxied) highlighted. -. Fill in the identity fields (`name`, `description`, `enabled`) — same constraints as in xref:create-server.adoc[Create an MCP Server]. +. Fill in the identity fields (`name`, `description`, `enabled`); same constraints as in xref:create-server.adoc[Create an MCP Server]. . Provide the *URL* and *Transport*. . Configure authentication (see <>). . Click *Create*. @@ -52,17 +52,17 @@ If you don't already run a server, prefer a managed type — see xref:managed/ma Two transports are available on the proto enum `MCPTransport`: -* *SSE* — server-sent events. The traditional MCP transport. -* *Streamable HTTP* — newer bidirectional protocol. +* *SSE*: server-sent events. The traditional MCP transport. +* *Streamable HTTP*: newer bidirectional protocol. Pick whichever your server actually speaks. To probe a server quickly: [source,bash] ---- -# SSE handshake — expect a stream of `event:` lines on success. +# SSE handshake: expect a stream of `event:` lines on success. curl -N -H "Accept: text/event-stream" https://your-server.example.com/mcp/sse -# Streamable HTTP — expect a JSON-RPC response on success. +# Streamable HTTP: expect a JSON-RPC response on success. curl -X POST -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \ https://your-server.example.com/mcp @@ -86,7 +86,7 @@ The five auth modes from xref:create-server.adoc#configure-authentication[create |The upstream system supports OAuth client credentials and you want one shared identity for all callers. Provide `client_id`, `client_secret_ref`, `token_url`, and any required `scopes`. |*Token passthrough* -|The upstream server already validates client tokens — Redpanda just forwards the caller's `Authorization` header. +|The upstream server already validates client tokens; Redpanda just forwards the caller's `Authorization` header. |=== For user-delegated OAuth, the URL must be `https://` and you also need an OAuth Provider. See xref:user-delegated-oauth.adoc[User-delegated OAuth]. @@ -137,8 +137,8 @@ If the tools list is empty or stale, hit the *Refresh tools* action on the Overv |The server returned a `tools/list` response with an invalid JSON schema for one or more tool inputs. Fix the upstream tool's schema and refresh. |=== -== Out of scope +== Related topics -* *User-delegated OAuth consent flow* — see xref:user-delegated-oauth.adoc[User-delegated OAuth]. -* *Multi-server aggregation* (one MCP URL fronting many servers) — handled by AI Gateway. See xref:ai-gateway:aggregation.adoc[MCP aggregation]. -* *Server hosting and deployment guidance* — Redpanda doesn't operate self-managed servers; deployment, scaling, and patching are your responsibility. +* xref:user-delegated-oauth.adoc[User-delegated OAuth] for the consent flow. +* xref:ai-gateway:aggregation.adoc[MCP aggregation] for fronting many MCP servers behind a single URL with AI Gateway. +* Server hosting and deployment guidance is your responsibility: Redpanda doesn't operate self-managed servers; deployment, scaling, and patching are up to you. diff --git a/modules/mcp/pages/test-tools.adoc b/modules/mcp/pages/test-tools.adoc index 7af74f6..e5bfd61 100644 --- a/modules/mcp/pages/test-tools.adoc +++ b/modules/mcp/pages/test-tools.adoc @@ -120,8 +120,8 @@ rpk ai mcp get The command resolves the gateway URL from your active rpk cloud profile and reads the cached `rpk cloud login` token. See xref:ai-gateway:connect-agent.adoc[Connect your agent] for installation and profile setup. -== Out of scope +== Related topics -* *Pointing an agent at the server*: see the Agents docs. -* *Aggregating multiple servers*: see xref:ai-gateway:aggregation.adoc[MCP aggregation]. -* *Debugging the upstream system itself* (your SQL database, your Slack app): outside the scope of MCP tooling. +* xref:ai-gateway:aggregation.adoc[MCP aggregation] for fronting many MCP servers behind a single URL. +* For pointing an agent at the server, see the Agents docs. +* The Inspector tests the MCP server, not the upstream system. Debugging the upstream system itself (your SQL database, your Slack app) is outside the scope of MCP tooling. diff --git a/modules/mcp/pages/user-delegated-oauth.adoc b/modules/mcp/pages/user-delegated-oauth.adoc index b24fa5b..b20efe8 100644 --- a/modules/mcp/pages/user-delegated-oauth.adoc +++ b/modules/mcp/pages/user-delegated-oauth.adoc @@ -95,8 +95,8 @@ For the field-by-field service-account-OAuth setup, see xref:create-server.adoc# |Connections persist until manually revoked. Have the user remove and re-add the connection if upstream credentials changed. |=== -== Out of scope +== Related topics -* *Configuring an OAuth provider*: separate workflow under the *OAuth providers* section. -* *Service-account OAuth setup*: see xref:create-server.adoc#configure-authentication[create-server.adoc]. -* *Token vault internals*: Redpanda manages the vault; users see their own connections under *My Connections*, but the underlying storage isn't user-configurable. +* xref:oauth-providers.adoc[Configure an OAuth Provider] for the separate workflow that creates the providers referenced from MCP servers. +* xref:create-server.adoc#configure-authentication[Service-account OAuth setup] for the shared-identity alternative. +* Token vault internals are not user-configurable. Redpanda manages the vault; users see their own connections under *My Connections*.