# Connect an API service to Thegram

Use this connection for a backend or external service with a remote MCP client that supports Streamable HTTP and custom authentication headers. No desktop app or coding-agent plugin is required. This is MCP over HTTP (JSON-RPC 2.0), not a general REST API. An OAuth-only connector must use its supported OAuth integration instead.

## 1. Issue a service-specific key

Sign in at https://vault.thegram.one/v3/ and open **Settings → Agents → API keys**. Name the key for the external service, select only the required vaults and Drive accounts, and grant the minimum permissions. Prefer read access unless writes are required. Keys expire within 90 days; the secret is shown once.

Use a separate key for each service. It cannot exceed your current vault membership or organization policy, and a vault grant is not a document-only sandbox. Local-only documents are not uploaded automatically.

## 2. Configure the service

Field names depend on the MCP client:

| Setting | Value |
|---|---|
| MCP server URL | `https://vault.thegram.one/mcp` |
| Transport | Streamable HTTP |
| Authentication | API key / Bearer token |
| Header name | `Authorization` |
| Header value | `Bearer <THEGRAM_API_KEY>` |

Replace the placeholder only in the service's private credential field or secret manager. If the client provides a Bearer-token field, enter just the key, without duplicating the `Bearer ` prefix.

For a custom backend, use its MCP SDK over HTTPS POST with `Content-Type: application/json` and `Accept: application/json, text/event-stream`. Let the SDK send `initialize`, negotiate the supported protocol version, send the initialized notification, and carry returned session/protocol headers on subsequent requests. Include the Bearer header on every request. Do not guess REST routes from MCP tool names.

Only connect services you trust: they receive the key and can access the authorized data. Keep it in an encrypted credential store or server-side secret manager. Never put it in a URL, browser JavaScript, chat, committed configuration or request logs. Do not send the key to a different endpoint or follow a redirect with it.

## 3. Verify without writing

Use the service's MCP connection check and `tools/list` to discover the current tool schemas. Call `gram_capabilities` and `gram_projects` with empty arguments to inspect the authorized connection. Read an existing document only in the intended scope if needed. Do not create a test document, overwrite data, or broaden permissions to make a connection check pass.

A successful tool listing does not prove access to every vault. If the service cannot send a custom Authorization header, use a supported OAuth connector or a server-side MCP client rather than exposing the key in a public frontend.

## 4. Revoke and rotate

- HTTP 401: check the endpoint, Bearer header, expiry and revocation status. Replace the key in the service's private credential store when needed.
- Access denied or a missing vault: inspect selected scopes, membership and organization policy; do not automatically grant broader access.
- Revoke the key in Thegram Settings to stop server access. Removing only the service connection does not revoke it.
- To rotate: issue a new scoped key, update the service, verify read-only access, then revoke the old key.

Guide for people: https://thegram.one/install/#api-services
Coding-agent plugin: https://thegram.one/install/agents.md
ChatGPT OAuth: https://thegram.one/install/chatgpt.md
Support: support@thegram.one