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

# Model Context Protocol (MCP)

> Give Claude, Cursor, or any MCP client your workflows, skills, and knowledge base — through a hosted server you authorise once.

Valendata runs a hosted MCP server. Connect it to Claude, Cursor, VS Code, or any MCP client and that assistant can list your published workflows, run them, read the results, run your skills, and read and write your knowledge base — as you, with the permissions you grant.

There is nothing to install. The server is remote, and you authorise it in the browser the same way you would connect any other app to your account.

## Connect

The server URL is:

```
https://api.valendata.com/mcp/sse
```

<Note>
  Settings → Connectors has this URL along with copy-paste configuration for Claude, Cursor, and VS Code. Use that page if you would rather not hand-write the config.
</Note>

For a client that takes a remote MCP server directly:

```json theme={null}
{
  "mcpServers": {
    "valendata": {
      "url": "https://api.valendata.com/mcp/sse"
    }
  }
}
```

The first time the client connects, your browser opens a Valendata consent screen listing exactly what the client is asking for. You approve or decline, and the client stores the resulting token itself.

<Note>
  Authorisation is OAuth 2.1 with PKCE, so a client never holds your password and you can withdraw its access at any time from Settings → Connectors. If a client cannot do OAuth, it can send a Valendata API key instead (`Authorization: Bearer vd_sk_…`). The key brings its own [scopes](/account/api-keys#scopes): a key with only `skills:read` can list and describe skills but not run them. Step-by-step setup for Claude, ChatGPT, Meta Muse, and Cursor is in [Connect your AI assistant](/integrations/connect-ai-assistants).
</Note>

Most current clients (Claude, ChatGPT, Cursor) use Streamable HTTP at `https://api.valendata.com/mcp`. Use `/mcp/sse` only for clients that support SSE alone. Both serve the same tools.

## Permissions

You grant scopes at the consent screen, and each tool checks the one it needs. Grant only what the assistant actually has to do.

| Scope | What it allows |
| - | - |
| `workflows:read` | See your published workflows and read run results |
| `workflows:invoke` | Start a workflow. Spends credits |
| `skills:read` | See your skills and their details |
| `skills:invoke` | Run a skill. Spends credits. An OAuth grant of this scope also allows `create_skill` and `improve_skill` |
| `skills:write` | API keys only: create a skill with `create_skill`, or fix, extend, or re-learn one with `improve_skill`. Spends credits |
| `knowledge:read` | Read facts from your knowledge base |
| `knowledge:write` | Save and update facts in your knowledge base |

The two `invoke` scopes are the ones that cost money. Everything they run is billed to your account exactly as if you had pressed Run yourself.

## Tools

### Workflows

<ResponseField name="list_workflows" type="no arguments">
  Your published workflows, with the id each one is invoked by. Needs `workflows:read`.
</ResponseField>

<ResponseField name="invoke_workflow" type="workflow_id, inputs?">
  Starts a workflow and returns a `run_id` straight away rather than waiting. A workflow can take anywhere from seconds to minutes, so the assistant polls `get_run_status` for the outcome. Needs `workflows:invoke`.
</ResponseField>

<ResponseField name="get_run_status" type="run_id">
  Status, per-step output, errors and timings for one run. Needs `workflows:read`.
</ResponseField>

<ResponseField name="list_recent_runs" type="limit?">
  The most recent runs across all your workflows, newest first. Defaults to 10, maximum 50. Needs `workflows:read`.
</ResponseField>

### Skills

<ResponseField name="list_skills" type="no arguments">
  Your active skills, public and private, with the id each one is run by. Needs `skills:read`.
</ResponseField>

<ResponseField name="invoke_skill" type="skill_id, params?, max_results?">
  Runs a skill and returns the extracted rows directly. Pass the skill's inputs as key/value pairs in `params`. `max_results` is 0–500 (`0` returns the whole list); leave it out to use the skill's saved default. Needs `skills:invoke`.
</ResponseField>

<ResponseField name="skill_<slug>" type="the skill's own inputs, max_results?, version?">
  One tool per skill you own or that is shared into your workspace, with the skill's typed input and output schema and a short track record in its description. Prefer these over `invoke_skill`. Listing them needs `skills:read`; calling them needs `skills:invoke`.
</ResponseField>

<ResponseField name="create_skill" type="task, start_url, name?, inputs?, output_fields?, idempotency_key?">
  Records the task in a cloud browser and publishes it as a private skill. Returns a `creation_id` at once. Needs `skills:invoke` and spends credits.
</ResponseField>

<ResponseField name="get_skill_creation" type="creation_id">
  Status of a `create_skill` request: `queued`, `recording`, `validating`, `ready`, or `failed`. Needs `skills:invoke`.
</ResponseField>

<ResponseField name="improve_skill" type="skill, mode?, feedback, fields?, example_input?, idempotency_key?">
  Changes one of your skills. `mode` is `fix` (default: a plain-English hint about where missing data is, "the phone is on the details page — click the place name…"), `add_fields` (capture new fields you describe, "also capture the star rating and review count"), or `relearn_details` (rebuild how it opens each result, when the site changed; `feedback` optional). A cloud browser relearns it and a short check run tests the new version; it goes live only if it is better, otherwise it is kept as a candidate. Returns an `improvement_id` at once. Owner or workspace editor only. Needs `skills:invoke` and spends credits.
</ResponseField>

<ResponseField name="get_skill_improvement" type="improvement_id">
  Status of an `improve_skill` request: `queued`, `working`, `validating`, `done`, or `failed`, with its `mode`, `result`, each target field's rows before → after, and any added, merged, or unclear fields in `details`. Needs `skills:invoke`.
</ResponseField>

### Knowledge base

<ResponseField name="get_knowledge" type="tags?">
  Facts from your knowledge base, optionally filtered by tag. Needs `knowledge:read`.
</ResponseField>

<ResponseField name="save_knowledge" type="key, value, tags?">
  Saves or updates one fact under `key`. `value` is any JSON object. Needs `knowledge:write`.
</ResponseField>

## Resources

Each published workflow is also exposed as an MCP resource, so a client can read its most recent results without running anything:

```
valendata://workflows/{workflow_id}/latest
```

Reading one returns the rows from that workflow's last completed run as JSON. This costs no credits — it is the run you already paid for. Resources need `workflows:read`.

## A typical exchange

Asking Claude for fresh data from a workflow you already built usually goes like this:

<Steps>
  <Step title="It finds the workflow">
    `list_workflows` returns your published workflows and their ids.
  </Step>

  <Step title="It starts a run">
    `invoke_workflow` returns a `run_id` immediately. Credits are consumed at this point.
  </Step>

  <Step title="It waits for the result">
    `get_run_status` is polled until the run reaches a terminal status, then the rows come back as JSON.
  </Step>
</Steps>

If yesterday's data would do, reading the workflow's `latest` resource skips the run and the cost entirely.

## Revoking access

Settings → Connectors lists every client you have authorised. Revoking one invalidates its token immediately; the client will ask for consent again the next time it connects. Nothing else about your account changes, and no other integration is affected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.