Sandbox Quick Start

The sandbox is a test environment where you can build and try your integration with ChronosHub on your own, without any effect on production. An AI assistant connection (an MCP server) guides you through the setup and answers your questions along the way. All sample data in the sandbox is fictional.

This page gets you started. The Sandbox page is the full reference.

Ask the MCP first

The MCP server is your first stop for any question about the ChronosHub Integration Framework: how inbound and outbound events work, what a payload looks like, what an error means, how webhook signatures are verified, rate limits and so on. It answers from this documentation, so you get the same answers you would find here.

You can reach the documentation in two ways:

• Through your AI assistant. Once the MCP server is connected (see below), just ask, for example "show me the docs about webhooks" or "what does the payload for this event look like?". The documentation tools need no API key, so this works before you have registered.
• On this site, where every page the assistant reads is published.

Onboarding

You need the invite code and the test environment host you received from your ChronosHub contact, and an AI assistant that supports MCP servers. Replace <host> in the examples with that host. The examples use Claude Code.

Connect the MCP server as a project (recommended)

Open a terminal in the folder you want to work in (a new, empty folder is fine) and run:

claude mcp add --transport http --scope project chronoshub-sandbox https://<host>/mcp

This stores the connection in a file called .mcp.json in that folder. We recommend it because it makes your API key easy to handle: during onboarding you receive a sandbox API key, and the onboarding explains what it is and how it is used. With a project, the key goes into .mcp.json, and then all you have to do is reconnect the MCP server.

Start the onboarding

Start Claude Code in the same folder (claude), approve the chronoshub-sandbox server when asked, and type:

onboard me

This starts a guided onboarding. Step by step, the assistant will:

• check that you know the basics (inbound and outbound events, webhooks and webhook signatures) and explain anything you don't;
• register you with your invite code;
• work out with you whether your flow is outbound (ChronosHub sends you events), inbound (you send events to ChronosHub) or both, and cover only what you need;
• help you choose the event contracts to test with, or draft your own;
• set up your webhook, if you receive events;
• test the flow for real, by receiving events on your webhook and sending events from your own system.

You set the pace. You can stop at any point and ask about anything you don't understand, and the assistant explains before moving on. If you get stuck, reach out to your ChronosHub contact.

We'd love your feedback. This is a new way of onboarding, and anything you tell us, good or bad, helps us make the MCP experience better.

Your API key and webhook secret

When you register, the assistant gives you two links: one for your API key and one for your webhook secret. Open each one in your browser and click Reveal. Each link works once and for a limited time (normally 60 minutes; the assistant tells you when it expires), so save the secret as soon as you see it. This is also how ChronosHub hands over your credentials for staging and production.

• Webhook secret. Put it in your webhook receiver's configuration, where it verifies that events really come from ChronosHub. Keep it out of the chat; the assistant doesn't need it.
• API key. The MCP connection needs it for everything after registration. Choose how to add it:

  • Add it yourself. The assistant shows you where it goes for your setup. With a project, you add it to .mcp.json:

    {
      "mcpServers": {
        "chronoshub-sandbox": {
          "type": "http",
          "url": "https://<host>/mcp",
          "headers": { "X-Api-Key": "<your API key>" }
        }
      }
    }

  • Paste it in the chat and let the assistant add it for you. The key then stays in your chat history. That's acceptable for the sandbox, and you can ask the assistant to replace the key while it still works.

Then reconnect: run /mcp, select chronoshub-sandbox and choose Reconnect, and tell the assistant to continue. Once .mcp.json contains your key, don't commit it to source control.

If a link expired before you used it, ask the assistant for a new one. If you revealed your API key and then lost it, the assistant can't recover it: ask your ChronosHub contact for a new key.

Not using a project?

If you added the server without --scope project, replace it from a terminal once you have your API key:

claude mcp remove chronoshub-sandbox
claude mcp add --transport http chronoshub-sandbox https://<host>/mcp --header "X-Api-Key: <your API key>"

Then restart Claude Code and say "let's continue".

Other assistants that support MCP, such as Cursor, work too; see Sandbox for their setup.

Test files

Not every flow involves manuscript files, so skip this if yours doesn't. If it does, the sandbox comes with a set of sample manuscripts (Word, PDF and LaTeX, all fictional) that you can use in your test events. Ask the assistant to "list the sample files", and it can create a download link for any of them. You are also welcome to upload and test with your own files.

Event contracts are for testing

An event contract is the schema an event's payload must match. In the sandbox you can use existing contracts and draft your own, so you can test your flow without waiting for anyone. These contracts are for testing only. The contracts for staging and production are agreed together by you and ChronosHub: your drafts are a useful starting point for that conversation, not the final version.

When are you ready?

Readiness in the MCP

At any time, ask the assistant to "check my readiness". It shows, for each event type and direction you have worked with, whether it is not started, in progress, failing or passing. You count as ready in the sandbox when every direction you have tested has worked at least once: if you receive events, at least one was delivered to your webhook; if you send events, at least one was accepted and processed.

Ready for the next step

Sandbox readiness shows that the connection works, but the integration itself lives in your systems, not in the MCP. Come back to us when you have:

1. a working webhook that receives our events and verifies their signatures;
2. an automated flow in your own code that processes the events you receive and sends events to ChronosHub, without using the MCP.

From there, we agree the final event contracts with you and set up the same integration in staging and production, with new credentials.