Connect your agent with MCP

Connect your SignalShelf instance

Start SignalShelf, then create an API key in your workspace. The local MCP address is https://signalshelf.dev/mcp. Use your deployment's HTTPS origin followed by /mcp for a remotely hosted instance. A localhost address works only when the client runs on the same machine as the server.

Choose a client that supports Streamable HTTP and secret request headers. Set x-api-key to your SignalShelf key, or send Authorization: Bearer followed by that key. Supply the credential on every request. Store it in the client's secret settings or environment; do not put it in a URL, public config file or tool argument.

This endpoint uses API-key authentication. It does not provide OAuth discovery or an interactive OAuth login. Dashboard cookies alone do not authenticate MCP requests. Client connection fields vary, so select the Streamable HTTP transport and enter the URL and secret header using your client's instructions.

MCP endpoint: https://signalshelf.dev/mcp
Transport: Streamable HTTP
Secret header: x-api-key: YOUR_SIGNALSHELF_KEY
Alternative: Authorization: Bearer YOUR_SIGNALSHELF_KEY

Discover tools before spending credits

Ask the agent to call signalshelf_capabilities. It lists implemented GitHub, Bluesky, YouTube and Apple Music catalog resource names, their required parameters, available profile platforms and credit rules. The same reference is available as the signalshelf://capabilities MCP resource.

Start with signalshelf_profile in demo mode, which is also the default. Its profile data is clearly labeled as an illustrative sample and costs zero credits. Explicitly choose live when you need real public data. A sample is useful for exploring the integration, but it must never be presented as evidence about a real creator.

Tool: signalshelf_profile
Arguments:
{
  "platform": "instagram",
  "handle": "alexmorgan",
  "mode": "demo",
  "freshness": "24h"
}

Choose the tool for the job

signalshelf_profile returns one public profile. signalshelf_batch accepts up to ten profile inputs, validates the whole batch before starting and reports source failures for each item. signalshelf_resource fetches an implemented GitHub, Bluesky, YouTube or Apple Music catalog resource using its documented params and pagination.

signalshelf_credits reads your current database balance. signalshelf_usage reads up to 100 of your recent lookup events, defaulting to 20. signalshelf_capabilities, balance, usage and capability-resource reads do not start source requests or spend credits. The server exposes no key-management, payment or arbitrary URL-fetching tools.

Tool: signalshelf_resource
Arguments:
{
  "platform": "github",
  "resource": "repositories",
  "params": {"handle": "octocat", "limit": 10, "page": 1},
  "freshness": "24h"
}

Keep costs, freshness and source content visible

A successful fresh live result costs one credit. Accepted cache hits, samples and failures cost zero. Read meta.credits_charged, meta.cache and meta.fetched_at in the result. Freshness accepts live, 1h, 24h or 7d, with 24h as the default. Different resource parameters and pages select different cached results.

Tell your agent how many fresh credits it may spend and how old accepted data can be. Lookup tools are marked as changing state because a source read can also cache data and debit credits. Public biographies and post text are untrusted content to analyze; an agent must not obey instructions embedded in them.

An operation failure returns an MCP tool result with isError set to true. Domain errors include a code, message and HTTP-style status. The MCP SDK handles invalid tool schemas. A batch can partially succeed, so inspect every item rather than treating a returned batch as proof that every lookup worked.

Protocol and connection behavior

The endpoint implements stateless Streamable HTTP using the official MCP SDK. A standard client initializes the connection, negotiates the protocol version and sends JSON-RPC POST requests. The server returns JSON and does not issue an MCP session ID. GET event streams and DELETE session termination return 405.

Each request is authenticated independently. Revoking a key disables subsequent requests using it. A 401 means the credential is missing, invalid or revoked. Origin and host checks apply; a client on another machine needs the actual configured deployment address rather than the local preview URL.

MCP exposes existing SignalShelf operations. It does not turn planned transcripts, platform search or ad-library endpoints into working tools. Check current capabilities and coverage before assigning an agent a workflow that depends on them.