> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect an MCP server
> Connect a Streamable HTTP MCP server, choose when its tools load, and verify each sync.
Connect the public Faker MCP server and expose its three tools to an [agent variation](/docs/guides/configure-a-simple-agent). 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
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](/docs/guides/store-and-use-secrets), then reference it with `${SECRET_NAME}`:
```text theme={null}
Authorization: Bearer ${MCP_SERVER_TOKEN}
```
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.
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.
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.
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](/docs/guides/preventing-tool-bloat) builds both policies with a larger tool source.
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.
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.
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.
```typescript TypeScript theme={null}
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));
}
```
```bash cURL theme={null}
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
Assign Faker MCP to a variation and run it.
Combine include, exclude, approval, and progressive discovery controls.
Keep provider tokens out of tool set configuration.
Create, update, assign, archive, and inspect tool sets from code.