Connect Valendata to your AI assistant

Valendata runs a hosted Model Context Protocol (MCP) server. When you connect it to an AI assistant, the assistant can run the skills and workflows you built in Valendata, create new skills from a task you describe, and read or save facts in your knowledge base. It does this as you, only with the permissions you approve, and you can disconnect it at any time. Each skill runs a task you set up, on a website you choose. It runs either in your own logged-in browser through the Valendata extension, or in a Valendata cloud browser. Nothing runs until you or your assistant asks for it, and every run is billed to your account in the same way as when you press Run yourself.

You are responsible for making sure you may access the sites and data your skills use. Follow each site’s terms of use and rate limits. See the Terms of Service.

Before you start

A Valendata account at www.valendata.com.
At least one published skill or workflow, or credits to create a skill from your assistant (see Credits and billing).
An assistant that supports remote MCP servers.

Server URL

Transport	URL	Use it for
Streamable HTTP (recommended)	`https://api.valendata.com/mcp`	Claude, ChatGPT, Meta Muse, Cursor, and most current clients
Server-Sent Events (SSE)	`https://api.valendata.com/mcp/sse`	Older clients that only support SSE

Both URLs serve the same tools. You can also copy them from Settings → Connectors in the Valendata app. Valendata uses OAuth 2.1 with PKCE. You never give your password to the assistant.

Add the server URL in your assistant

Follow the steps for your assistant below. Choose OAuth if the assistant asks for an authentication type.

Your browser opens Valendata. Sign in if you are not already signed in.

Review the consent screen

The consent screen shows the name of the app that is asking and the permissions (scopes) it requested. Untick any permission you do not want to grant, then click Allow access. Click Deny to refuse.

Start using the tools

You return to your assistant. Its tool list now includes your Valendata tools.

The assistant registers itself with Valendata automatically the first time it connects (OAuth dynamic client registration). You do not need to create a client ID or secret.

Permissions (scopes)

Each tool checks for the scope it needs. Grant only what the assistant has to do.

Scope	Label on the consent screen	What it allows
`workflows:read`	Read workflows	View your published workflows and their run results
`workflows:invoke`	Invoke workflows	Run your published workflows. Uses credits
`skills:read`	Read skills	View your skills and their details
`skills:invoke`	Invoke skills	Run your skills, and create new skills. Uses credits
`knowledge:read`	Read knowledge base	Read facts stored in your knowledge base
`knowledge:write`	Write knowledge base	Save and update facts in your knowledge base

The two invoke scopes are the only ones that spend credits.

Tokens

The assistant receives an access token and a refresh token. Valendata stores only a hash of each token, never the token itself.
Access tokens are short-lived. The assistant uses the refresh token to get a new pair without asking you again.
Each refresh token works once. If a used refresh token is presented again, Valendata treats it as stolen and revokes every token from that sign-in. You then sign in again.

Connect your assistant

Menu names in these apps change from time to time. If a label below does not match exactly, look for the option to add a custom connector or a remote MCP server.

Claude
ChatGPT
Meta Muse
Cursor
Other MCP clients

Works in Claude on the web and in the Claude desktop app.

In Claude, open Settings → Connectors.
Click Add custom connector.
Enter a name, such as Valendata, and the URL https://api.valendata.com/mcp.
Click Add, then Connect. Sign in to Valendata and approve access.
In a chat, open the tools menu and make sure Valendata is turned on.

On Claude Team and Enterprise plans, an organization owner may need to add the connector before members can connect it.

In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
Back in Apps & Connectors, click Create.
Enter a name, such as Valendata. Set MCP Server URL to https://api.valendata.com/mcp and Authentication to OAuth.
Click Create. Sign in to Valendata and approve access.
In a chat, choose Valendata from the tools or connectors menu.

Developer mode availability depends on your ChatGPT plan and workspace settings.

In Meta Muse, open the connector settings and choose to add a custom MCP connector.
Enter a name, such as Valendata, and the server URL https://api.valendata.com/mcp.
Choose OAuth sign-in if asked. Sign in to Valendata and approve access.
Turn on the Valendata connector in your conversation.

Add Valendata to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "valendata": {
      "url": "https://api.valendata.com/mcp"
    }
  }
}

Save the file. Cursor opens the Valendata sign-in page the first time it connects. You can also add the server from Cursor Settings → Tools & MCP.

Any client that supports remote MCP servers with OAuth works. Point it at https://api.valendata.com/mcp (or /mcp/sse for SSE-only clients).Clients discover the sign-in endpoints from these standard metadata documents:

https://api.valendata.com/.well-known/oauth-protected-resource (RFC 9728)
https://api.valendata.com/.well-known/oauth-authorization-server (RFC 8414)

An unauthenticated request to the MCP endpoint returns 401 with a WWW-Authenticate header that points to the protected-resource document.

Use an API key instead of OAuth

If your client or agent runtime cannot do an OAuth sign-in, send a Valendata API key as the bearer token:

Authorization: Bearer vd_sk_YOUR_API_KEY

For example, in a client that accepts custom headers:

{
  "mcpServers": {
    "valendata": {
      "url": "https://api.valendata.com/mcp",
      "headers": {
        "Authorization": "Bearer vd_sk_YOUR_API_KEY"
      }
    }
  }
}

An API key carries the scopes you picked when you created it. Make a key just for the assistant with only what it needs. For example, leave out skills:invoke and workflows:invoke if it should not spend credits. Keep keys out of shared config files, and revoke a key from Settings → API Keys if it leaks. See API keys.

Tools

Your skills: `skill_<slug>`

Every skill you can run appears as its own tool, named skill_ plus the skill’s slug. For example, a skill with the slug austin-dentists becomes skill_austin-dentists. These tools include:

Skills you own.
Skills shared into a workspace you belong to.

Public marketplace skills appear only after you clone them into your account. Only skills that are published or active are listed. Each skill tool includes:

A description: what the skill does, plus a short, honest track record (total runs, recent success rate, typical time and row count, the last error if there was one, and its fast path if it has one).
An input schema: the skill’s own typed inputs, plus two optional controls:
- max_results (0–500, where 0 returns the whole list).
- version (replay a specific recipe version; see How Valendata keeps skills working).
An output schema: the shape of the result, so the assistant can rely on the field names.

Listing these tools needs skills:read. Calling them needs skills:invoke. The tool list is rebuilt each time the assistant refreshes it, so a skill you publish shows up on the next refresh. A call that breaks the input schema is rejected before anything runs. The error lists each problem and the inputs the skill accepts. If too many of your runs are already in progress, the call returns at once with a message that tells you when to retry.

Create a skill from a task

Tool	Arguments	Scope
`create_skill`	`task`, `start_url`, optional `name`, `inputs`, `output_fields`, `idempotency_key`	`skills:invoke`
`get_skill_creation`	`creation_id`	`skills:invoke`

create_skill does the task once in a Valendata cloud browser, records it, and publishes it as a private skill with typed inputs and output columns. It returns a creation_id straight away. Recording takes a few minutes. The assistant calls get_skill_creation until status is ready (the new skill_<slug> tool then appears) or failed (error says why). Skill creation uses credits and cannot sign in to websites. See the Web to API guide for limits.

Improve a skill

Tool	Arguments	Scope
`improve_skill`	`skill` (the slug, or the `skill_<slug>` tool name), optional `mode` (`fix`, `add_fields`, or `relearn_details`), `feedback`, optional `fields`, `example_input`, `idempotency_key`	`skills:invoke`
`get_skill_improvement`	`improvement_id`	`skills:invoke`

improve_skill has three modes:

fix (default): when a skill run comes back short, its result carries a diagnosis: for each missing field, how many rows had it, where the skill looked, and example hints. The assistant passes a plain-English hint, for example “the phone is on the details page — click the place name, the panel opens, the number is next to the phone icon”.
add_fields: capture new fields described in plain English, for example “also capture the star rating and review count”. A field the skill already has under another name is merged into it, and an unclear one comes back as a question.
relearn_details: rebuild how the skill opens each result, when the site changed or detail fields come back empty. feedback is optional here.

A cloud browser relearns the skill, and a short check run (up to 5 rows) tests the new version. If it is better, the new version goes live. If not, it is kept as a candidate and the old version stays live. improve_skill returns an improvement_id straight away; the assistant calls get_skill_improvement until status is done (result, changes, and details say what changed) or failed. Only the skill’s owner or a workspace editor can improve it, and it uses credits. See Improve a skill.

Generic skill tools

Tool	Arguments	Scope	What it does
`list_skills`	none	`skills:read`	Lists the active skills you own, with their IDs
`invoke_skill`	`skill_id`, optional `params`, `max_results`	`skills:invoke`	Runs a skill by ID. Prefer the `skill_<slug>` tools, which carry typed schemas

Workflows

Tool	Arguments	Scope	What it does
`list_workflows`	none	`workflows:read`	Lists your published workflows and their IDs
`invoke_workflow`	`workflow_id`, optional `inputs`	`workflows:invoke`	Starts a workflow and returns a `run_id` at once
`get_run_status`	`run_id`	`workflows:read`	Status, per-step output, and errors for one workflow run
`list_recent_runs`	optional `limit` (default 10, max 50)	`workflows:read`	Your most recent workflow runs, newest first

Each published workflow is also an MCP resource at valendata://workflows/{workflow_id}/latest. Reading it returns the rows from that workflow’s last completed run. This uses no credits. Resources need workflows:read.

Knowledge base

Tool	Arguments	Scope	What it does
`get_knowledge`	optional `tags`	`knowledge:read`	Reads facts from your knowledge base
`save_knowledge`	`key`, `value` (a JSON object), optional `tags`	`knowledge:write`	Saves or updates one fact

Disconnect and revoke access

You can cut off an assistant from either side.

In Valendata: open Settings → Connectors. Under connected apps, click Revoke next to the app. All of that app’s access and refresh tokens stop working at once. The assistant asks you to sign in again the next time it connects.
In your assistant: remove or disconnect the Valendata connector. This stops the assistant from calling Valendata, but it does not revoke tokens on Valendata’s side. Revoke in Valendata as well if you want to be sure.
API keys: if you connected with an API key, revoke that key in Settings → API Keys.

Clients can also revoke a token themselves by sending it to POST https://api.valendata.com/oauth/revoke (RFC 7009). Revoking a refresh token also revokes every token from the same sign-in. Revoking an assistant does not delete your skills, workflows, runs, or knowledge base, and does not affect your other connections.

Troubleshooting

The assistant shows no skill tools

Check that you granted skills:read, and that you have at least one published or active skill. Then refresh the tool list or reconnect.

A tool returns "missing ... scope"

You did not grant that scope at sign-in. Revoke the app in Settings → Connectors, reconnect, and tick the scope on the consent screen.

Calls fail with insufficient credits

Running and creating skills uses credits. Top up from the billing page. See Credits and billing.

Get Started

Core Concepts

Guides

Integrations

Account & Security

Connect Valendata to your AI assistant

Before you start

Server URL

Permissions (scopes)

Tokens

Connect your assistant

Use an API key instead of OAuth

Tools

Your skills: `skill_<slug>`

Create a skill from a task

Improve a skill

Generic skill tools

Workflows

Knowledge base

Disconnect and revoke access

Troubleshooting

​Before you start

​Server URL

​Sign-in and consent

​Permissions (scopes)

​Tokens

​Connect your assistant

​Use an API key instead of OAuth

​Tools

​Your skills: skill_<slug>

​Create a skill from a task

​Improve a skill

​Generic skill tools

​Workflows

​Knowledge base

​Disconnect and revoke access

​Troubleshooting

Before you start

Server URL

Sign-in and consent

Permissions (scopes)

Tokens

Connect your assistant

Use an API key instead of OAuth

Tools

Your skills: `skill_<slug>`

Create a skill from a task

Improve a skill

Generic skill tools

Workflows

Knowledge base

Disconnect and revoke access

Troubleshooting