> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groundforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Notes

> Important behaviour to know when using the SaaS platform, Channels, SDK, and MCP workflows.

These notes come from the current runtime behaviour and prevent common configuration mistakes.

## Scope matters

Check the active Organization and Workspace before creating an Agent, Channel, MCP provider, Gateway, credential, or Trace query. Resources in different Workspaces cannot be combined in one request.

## Publish after attaching a Channel

Attach the Channel to the Agent, save, and publish the Agent before configuring the provider callback. Use the generated URL with immutable Agent and Channel IDs:

```text theme={null}
https://platform.groundforge.ai/v1/agents/{agent_id}/channels/{channel_id}/callback
```

Renaming a display name does not change those IDs.

## Provider signatures are verified

Twilio and Mailgun callbacks are verified before GroundForge normalizes or processes the message. Copy the callback exactly and keep the signing credential current.

## Twilio sender and test recipient are different

Store the WhatsApp sender in the Channel. Pass the recipient only when running a Channel test. In the Twilio sandbox, the recipient must have joined the sandbox, and sender and recipient must not be the same number.

## External Agents must stay connected

An external Agent receives Channel jobs only while its SDK process is running with `serve=True`. Direct tracing with `serve=False` does not receive Channel jobs.

## Credentials are write-only

Model keys and other generated secrets are not returned after they are saved. Store the original value in a protected secret manager. A model credential belongs to the Agent; a Channel credential belongs to the Channel; an MCP connection credential belongs to the provider.

## Local stdio secrets stay local

When `gforge` discovers a local stdio MCP server, environment secret values remain on that machine. GroundForge uploads capability definitions, not raw local environment secrets.

## Discovery is explicit

Opening Observations or Drifts reads saved records. It does not run Discovery. Start a new Discovery only when you want GroundForge to read the current Agent or MCP capability definitions.

## GroundForge does not invent audience metadata

Country, region, city, language, or campaign breakdowns appear only when a Channel or caller supplies reliable data. GroundForge does not perform IP geolocation and external-Agent examples do not assume custom `user_id` metadata.

## Historical Traces keep their original detail

A newer SDK or UI can improve future Trace structure, but it cannot reconstruct model, tool, parent-run, or Channel details that were never recorded in older requests.

## Example

Before testing the LangChain weather Agent, confirm the Workspace, keep the Agent running, publish the Channel attachment, run a dry-run delivery test, and then send one new request. This gives you a clean Trace to compare with the expected flow in [LangChain Agent Example](/examples/langchain-agent).


## Related topics

- [Dashboard](/platform/dashboard.md)
- [Introduction](/index.md)
- [Analytics](/observability/analytics.md)