> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Agents & Workflows with MCP

> Connect your AI assistant to Response and Workstream, verify its access, and use guided tasks to build agents and operate workflows.

<div className="ss-guide-summary" role="group" aria-label="Walkthrough at a glance">
  <div><span className="ss-eyebrow">WORK IN</span><strong>Your MCP assistant</strong></div>
  <div><span className="ss-eyebrow">BRING</span><p>MCP host · Model access · Service credentials</p></div>
  <div><span className="ss-eyebrow">FINISH WITH</span><p>Verified workspace identity from actual tool results</p></div>
</div>

Explore [what you can build with the Rust engines and MCP](/guides/rust-engines-and-mcp) to choose the right system for your operation.

Use your own AI assistant to inspect and manage StateSet. **Response MCP** manages support
agents, rules, knowledge, tests, and response history. **Workstream MCP** manages workflow
brands, connectors, configuration, trials, and execution evidence.

Your assistant supplies the model and user interface; these MCP servers supply the tools and
authorization. Connecting a server does not automatically grant every operation or complete onboarding.

## Choose the smallest useful task

You can finish this walkthrough after verifying access. Agent creation, workflow trials, and
configuration changes are independent follow-on tasks; you do not need to run all of them.

| Start with               | You need                                                                             | Save as evidence                                         |
| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| Read your workspace      | MCP host, model access, and an accepted service credential                           | Actual organization or brand identity from tool results  |
| Create and test an agent | Response connection with creation and generation permissions, plus a policy          | Agent ID, saved configuration, and observed test answers |
| Trial a workflow         | Workstream connection, provider readiness, and authorization for accelerator changes | Job ID, step results, and a verified replay/run          |
| Propose an improvement   | Access to the relevant configuration and run evidence                                | Current version, proposed diff, and evaluation results   |

Start with the read-only connection check below. Keep the verified identifiers and permitted
actions in your [onboarding record](/guides/platform-onboarding#keep-a-record-you-can-resume).
Never treat a successful connection as authorization for every later task.

## 1. Connect the server for your task

| Server     | Remote HTTP endpoint                         | First useful read                                                  |
| ---------- | -------------------------------------------- | ------------------------------------------------------------------ |
| Response   | `https://response.stateset.com/api/mcp`      | `describe_workspace`, then `describe_vocabulary`                   |
| Workstream | `https://api.workstream.stateset.com/v1/mcp` | `list_brands`, then `get_onboarding_funnel` for the selected brand |

If you used the provisioning portal, open [MCP connections](https://onboarding.stateset.com/mcp).
Select the required services and your client, then copy the client-specific configuration.
The portal includes exports for Claude Code, Claude Desktop, and Cursor; use your host's
supported remote-connection flow if it uses a different configuration format.

The portal distinguishes **Ready**, **Not provisioned**, **Needs a key**, and **Not released yet**.
Provision the service or resolve its connection requirement before expecting tools to work.
Create a workspace key if that feature is enabled and store it securely when shown. A lost key
must be rotated; it cannot be recovered from the displayed prefix.

### Choose a credential the server accepts

* **Response:** use its configured OAuth connection, a scoped `rcx_` API key, or a portal workspace
  key when workspace-key verification is enabled for that deployment.
* **Workstream:** use its supported OAuth flow or an authorized per-brand API key. If the portal
  supplies a workspace-key configuration, verify that the deployed server accepts it before
  relying on it; the portal catalogue alone does not prove end-to-end authentication.

See [Response MCP](/stateset-response/response-mcp) and
[Workstream MCP](/next-temporal/mcp-connector) for service-specific setup. Do not use a Response
key as a Workstream key merely because both use a Bearer header.

Supply secrets using your host's credential mechanism. An exported `${STATESET_API_KEY}` is a
placeholder until your client resolves it; environment-variable syntax and support differ by
host. Do not paste credentials into an agent conversation. If workspace keys are not enabled,
use the supported service credential or ask your administrator to enable the connection.

## 2. Verify access before requesting changes

Reconnect or refresh tools in the host, then ask:

```text theme={null}
Inspect the tools exposed by my StateSet connections. Make no changes.
For Response, call describe_workspace and describe_vocabulary if available.
For Workstream, list the brands I can access and report their identifiers.
Tell me which workspace and brand these tools actually expose, which tools are
missing for onboarding, and what I need to provide next. Do not infer access
from a server name or documentation example.
```

<div className="ss-checkpoint">
  **Success:** actual tool results identify the intended organization and brand. Record the
  Response agent UUID and Workstream brand UUID when you select them; they are not interchangeable.
  If the host exposes paginated results, continue through the relevant pages before concluding
  that a record is missing.
</div>

Tool availability depends on credentials and deployment version. Inspect `tools/list` and the
input schemas instead of assuming a fixed tool count. A read-only task prompt is an instruction,
not a permission boundary: enforce the desired scopes and approvals in your server and host.

## 3. Build and verify a Response agent

After selecting the correct workspace, give your assistant this task. Replace the bracketed
values with your actual use case and policy references; these are instructions, not an API body.

```text theme={null}
Create one inactive support agent named [agent name] for [one support use case].
First inspect describe_vocabulary and the provision_agent schema. Use a supported
starter template and only the policies I supplied at [source references].
Keep the returned agent ID and an idempotency key for this creation attempt.
Read its saved configuration back before testing it.

You may create the agent and run test_agent for these three cases:
1. A question answered by the supplied policy.
2. An order question missing the identifying information.
3. A request requiring escalation under that policy.

Testing uses real model generation and may consume usage. Report each answer,
its expected behavior, and any failure. Do not activate the agent, connect a
customer-facing channel, send a customer message, or execute commerce actions.
```

`provision_agent` is the source's preferred tool for creating an agent with its settings, rules,
and functions together. Use `get_agent`, settings/rule reads, and the exposed evaluation tools
to verify what was saved. `test_agent` exercises the real generation path and requires
`responses:write`; it is not a read-only inspection tool.

<div className="ss-checkpoint">
  **Success:** a saved agent ID, inspected configuration, and three observed test results. If one
  fails, fix the specific source or behavior and preserve the case as an evaluation before launch.
  For the UI equivalent, use [your first support agent](/guides/first-support-agent).
</div>

## Run a workflow trial

Select or bootstrap the intended brand using the exposed templates and connect its providers
through an authorized connection flow. Keep secrets in the connection UI or credential store.
Then use a task such as:

```text theme={null}
For Workstream brand [brand UUID], inspect onboarding progress and readiness.
Confirm routing is shadow and explain any missing provider connections.
If prerequisites are satisfied, I authorize the onboarding accelerator to draft
and apply initial configuration, register provider webhooks, activate this shadow
brand, and replay up to 10 tickets. Preserve the human review gate.

Run run_onboarding_accelerator with background=true and backfill_limit=10.
Poll get_onboarding_accelerator_status; inspect failed and skipped steps.
Then read get_trial_report and one relevant workflow run. Report the draft,
run ID, dry-run outcome, remaining blockers, and next step.
Do not switch routing to canary/live or send replies to customers.
```

The accelerator makes configuration and provider changes even though replay sends no customer
reply. Its returned `job_id` means the job was accepted, not that every step succeeded. A
previously active brand follows the explicit configuration-edit path rather than receiving an
automatic draft overwrite. See [the trial walkthrough](/guides/first-workflow-trial).

## Improve an existing workflow

Use a separate task for tuning. Begin with actual performance and corrected examples:

```text theme={null}
Inspect brand [brand UUID]: current configuration/version, scorecard, and recent
failed or escalated runs. Propose one change backed by those results.
Use propose_config_patch and validate_config, then evaluate against the relevant
cases. Show me the diff, evidence, and expected effect before applying it.
Do not change routing, disable review, or lower evaluation thresholds.
```

When an application is authorized to apply the change, pass the current
`expected_config_version` and a meaningful `change_note` to `apply_config`. For unattended
agent edits, set `require_golden_pass: true`; stop on a missing/failing golden evaluation or
version conflict and reconcile before trying again. Read back the new configuration and inspect
subsequent runs. Configuration accepted is not the same as performance improved.

## Troubleshooting

| Symptom                                    | Next step                                                                                                   |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Server listed but connection returns `401` | Check endpoint, credential type, secret substitution, and whether workspace-key verification is enabled     |
| Tool missing or denied                     | Refresh discovery and check scopes, tenant access, and deployment version                                   |
| Agent test denied with reads working       | `test_agent` needs generation/write permission, not only `agents:read`                                      |
| Wrong workspace or brand appears           | Stop writes and reconnect/select the intended tenant; do not override tenant IDs to bypass credential scope |
| Accelerator still running                  | Poll its status; do not start another attempt just because the first call returned a job ID                 |
| Config apply conflicts                     | Fetch the current version and reevaluate the proposed change                                                |
| Host lacks HTTP MCP support                | Use its supported bridge or connection method; a raw server URL is not a stdio command                      |

## Save your progress

Before leaving, update your [onboarding record](/guides/platform-onboarding#keep-a-record-you-can-resume)
with the identifiers, observed result, remaining blocker, and next action. If you switch to an
AI assistant, use the [resume prompt](/guides/platform-onboarding#resume-with-your-ai-assistant)
to verify current state before continuing.

## Next steps

* [Your first configuration change](/guides/first-workflow-config-change): propose, evaluate, apply, and verify a versioned change.
* [Operate a durable agent](/guides/first-durable-agent): launch an approved task, inspect progress, and control its execution.
* [Your first evaluation](/guides/first-agent-evaluation): save a correction and compare behavior before and after a change.
* [Troubleshoot onboarding](/guides/onboarding-troubleshooting): find the blocked step and recover without duplicating work.
* [Your first week](/guides/first-week-with-stateset): review live outcomes, preserve corrections, and measure improvements.
* [From signup to first value](/guides/platform-onboarding): choose and measure the first outcome.
* [Agent operating procedure](/getting-started-for-ai-agents): task boundaries, evidence, and recovery.
* [Response MCP reference](/stateset-response/response-mcp) and [Workstream MCP reference](/next-temporal/mcp-connector).