Connect an MCP server

Connect the public Faker MCP server and expose its three tools to an agent variation. This guide starts with an empty workspace and explains both MCP loading modes.

What you need

A Cadenya workspace.
An MCP server with a Streamable HTTP endpoint. This guide uses https://free.cadenya.com/faker-mcp.
CADENYA_API_KEY and CADENYA_WORKSPACE_ID when you follow the code example.

Cadenya uses the MCP Streamable HTTP transport. A server that only supports the older HTTP+SSE transport cannot connect. Point Server URL at the server’s Streamable HTTP endpoint, often /mcp.

Create the tool set

Configure the connection

Select Tool Sets, click Create Tool Set, and select MCP. Enter https://free.cadenya.com/faker-mcp as the Server URL.Add headers when the server requires authentication. Store each credential as a secret, then reference it with ${SECRET_NAME}:

Authorization: Bearer ${MCP_SERVER_TOKEN}

MCP connection settings with the Faker Streamable HTTP endpoint entered as the Server URL — The MCP connection step with the Faker server URL

Click Generate Preview before you continue. Preview connects to the server and shows how the current filters affect its tool list without creating the tool set.

MCP Tools Preview listing GenerateCurseWord, GenerateFake, and GetFakerOptions as available — The three tools returned by the Faker MCP server

Choose when tools load

Click Continue to open Tool behavior. Keep the runtime switch off for this guide. Cadenya syncs the tools ahead of time and pins them to the tool set.

Tool behavior step with no filters, no approval requirement, and Just-in-time tool loading turned off — Filters, approval policy, and ahead-of-time MCP loading

The setting changes when and where tool discovery happens:

Mode	Just-in-time tool loading	Discovery	Dashboard tool list	Refresh
Synced	Off	After save, then in the background	Pinned tools appear on Tools	Every hour and after adapter updates
Just in time	On	When each objective starts	No pinned tools; the count stays at zero	Every objective gets the current server list

On-demand loading resolves the objective’s secrets before it lists tools. Use it when each objective has different credentials or the server exposes a different tool list per caller. Enable Fail objective when tools cannot be loaded when continuing without this tool set would make the objective invalid.

Set filters and approvals

Leave Include tools and Exclude tools empty so all three Faker tools remain available. Leave Approval requirement on No approval required.Filters control availability:

Include tools keeps only matching names, titles, or descriptions.
Exclude tools removes matching tools after the include rule runs.
An excluded synced tool remains visible as Omitted. Agents receive only Available tools.

Approval policy controls execution:

No approval required lets every available tool run.
Always require approval pauses every call.
Only matching tools require approval applies the approval rule to a filtered subset.

The separate filter and approval guide builds both policies with a larger tool source.

Name and create the tool set

Click Continue, enter Faker MCP as Name, and use faker-mcp as External ID. Add a description, review the configuration, then click Create Tool Set.Cadenya validates that the server can list tools before it saves the resource. After creation, the first background sync populates the Tools tab.

Verify the synced tools

Open the new tool set. The Tools tab shows three Available tools:

GenerateCurseWord
GenerateFake
GetFakerOptions

Select a tool to inspect the description and JSON parameter schema that the MCP server returned.

Faker MCP Tools tab showing three available tools and the selected tool's description and parameter schema — Faker MCP tools pinned to the tool set

Open Sync Events to audit discovery. A synced MCP tool set runs its first sync after creation and refreshes every hour. Updating its adapter also queues a sync.

Faker MCP Sync Events tab showing an initial three-tool sync followed by hourly syncs with no tool changes — Initial and hourly MCP sync events

The event count is the number of tools changed by that run, not the total tools in the set. An hourly refresh can report 0 tools while the unchanged three-tool list remains available. If a sync fails, Sync Events records the reason. Common failures include an unreachable URL and a header that references a missing secret.

Create the same configuration from code

The API returns an active tool set before the background sync finishes. Read its event log when setup code must wait for the tools.

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'] });
const workspaceId = process.env['CADENYA_WORKSPACE_ID']!;

const toolSet = await client.toolSets.create({
  workspaceId,
  metadata: { name: 'Faker MCP', externalId: 'faker-mcp' },
  spec: {
    adapter: {
      type: 'mcp',
      mcp: {
        url: 'https://free.cadenya.com/faker-mcp',
        justInTime: { enabled: false },
      },
    },
  },
});

while (true) {
  const events = await client.toolSets.listEvents(toolSet.metadata.id, {
    workspaceId,
    sortOrder: 'desc',
  });

  let pending = true;
  for await (const event of events) {
    const data = event.event;
    switch (data?.type) {
      case 'syncCompleted':
        console.log(`Synced ${data.syncCompleted.toolsSynced} tools`);
        pending = false;
        break;
      case 'syncFailed':
        throw new Error(data.syncFailed.message);
    }
    if (!pending) break;
  }

  if (!pending) break;
  await new Promise((resolve) => setTimeout(resolve, 1_000));
}

curl -X POST \
  "https://api.cadenya.com/v1/workspaces/${CADENYA_WORKSPACE_ID}/tool_sets" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "Faker MCP",
      "externalId": "faker-mcp"
    },
    "spec": {
      "adapter": {
        "type": "mcp",
        "mcp": {
          "url": "https://free.cadenya.com/faker-mcp",
          "justInTime": { "enabled": false }
        }
      }
    }
  }'

You now have a vetted MCP tool set with three synced tools. Assign the whole set to an agent variation, or assign one tool when the agent needs a narrower capability.

Next steps

Create and publish an agent

Assign Faker MCP to a variation and run it.

Filter a large tool source

Combine include, exclude, approval, and progressive discovery controls.

Store an MCP credential

Keep provider tokens out of tool set configuration.

Tool sets from the SDK

Create, update, assign, archive, and inspect tool sets from code.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Connect an MCP server

What you need

Create the tool set

Verify the synced tools

Create the same configuration from code

Next steps

Create and publish an agent

Filter a large tool source

Store an MCP credential

Tool sets from the SDK

​What you need

​Create the tool set

​Verify the synced tools

​Create the same configuration from code

​Next steps

Create and publish an agent

Filter a large tool source

Store an MCP credential

Tool sets from the SDK

What you need

Create the tool set

Verify the synced tools

Create the same configuration from code

Next steps