Developing Connectors

Using Claude Code with CDK

Claude Code is Anthropic's official CLI tool for working with Claude directly in your terminal. When paired with the TRAY CDK GUIDE.md file, it becomes a powerful assistant for building, testing, and deploying Tray CDK connectors.

What is TRAY CDK GUIDE.md?

TRAY_CDK_GUIDE.md is a comprehensive reference file designed specifically for Claude Code. It contains:

Complete CLI command reference for tray-cdk
End-to-end development flows
Project structure details
Authentication configuration patterns
HTTP and composite operation examples
Input/output configuration with UI annotations
Testing strategies
Deployment procedures
Troubleshooting tips

When placed in your project as a CLAUDE.md file, Claude Code automatically reads it at the start of every conversation, giving it full context about CDK development patterns and conventions.

Download TRAY CDK GUIDE file

The file is downloaded with a .txt extension. If you download it manually, rename it to CLAUDE.md before placing it in your project root.

Prerequisites

Claude Code installed on your machine. Follow the official installation guide .
Tray CDK CLI installed:

npm install -g @trayio/cdk-cli

An existing CDK connector project, or create one:

tray-cdk connector init my-connector -i

Setup

Download TRAY CDK GUIDE.txt

Download the guide file into the root of your CDK connector project and rename it to CLAUDE.md:

cd my-connector
curl -o CLAUDE.md https://tray.ai/documentation/files/cdk/TRAY_CDK_GUIDE.txt

Claude Code looks for a file named CLAUDE.md in the root of your project directory. By saving the guide as CLAUDE.md, Claude Code will automatically load it as context for every session.

Launch Claude Code

Navigate to your connector project and start Claude Code:

cd my-connector
claude

Claude Code will automatically detect and read the CLAUDE.md file when the session starts. You can verify this by asking Claude about CDK concepts — it will have full knowledge of the CLI commands, project structure, and development patterns.

Example workflows

Creating a new operation

> Add a new HTTP operation called "list_users" that calls GET /api/v2/users
  with pagination support

Claude Code will:

Scaffold the operation directory with input.ts , output.ts , handler.ts , and handler.test.ts
Configure the HTTP handler with the correct endpoint
Set up pagination parameters in the input schema
Write a matching test

Adding authentication

> Set up OAuth2 authentication for this connector using the "my-service"
  Tray service

Claude Code will update auth.ts and connector.json with the correct OAuth2 configuration referencing your Tray service.

Debugging a failing test

> The test for get_contact operation is failing with a 401 error.
  Help me fix it.

Claude Code will review the test setup, check auth mocking, and suggest fixes based on CDK testing patterns.

Deploying

> Deploy this connector to the EU region

Claude Code will run the appropriate tray-cdk deploy commands with the correct region flag.

Keeping the guide up to date

The TRAY_CDK_GUIDE.md file is versioned alongside the CDK documentation. To update to the latest version:

curl -o CLAUDE.md https://tray.ai/documentation/files/cdk/TRAY_CDK_GUIDE.txt

Tips

Be specific — Tell Claude Code exactly what third-party API you're integrating with and what operations you need.
Share API docs — If you have the third-party API documentation, share relevant endpoints so Claude Code can generate accurate handlers.
Run tests incrementally — Ask Claude Code to run npm test after each change to catch issues early.
Use composite operations wisely — If Claude Code suggests a composite handler, it's likely because the operation requires multiple API calls or data transformations.