# Puppetto Setup And Auth Guide For Agents

Use this file for deeper setup, authentication, API key, and OAuth instructions.

## Guest To Connected Organization

1. Ask the user to sign in or create an account at https://puppetto.com.
2. Ask the user to create or select an organization from `/organizations`.
3. Ask the user to open `/organizations/<orgId>/developer`.
4. Ask the user to generate a Puppetto MCP token for that organization.
5. Configure the MCP client with the org-scoped SSE URL and token header.
6. Verify with `puppetto_get_authorized_context`.

Guest sessions cannot call Puppetto MCP. The user must authenticate and authorize an organization token first.

## MCP Client Config

```json
{
  "mcpServers": {
    "puppetto": {
      "type": "sse",
      "url": "https://mcp.puppetto.com/mcp/org/<orgId>/sse",
      "headers": {
        "x-puppetto-api-v0-key": "${env:PUPPETTO_MCP_API_KEY}"
      }
    }
  }
}
```

## Token Handling

- Prefer an MCP client secret store or environment variable.
- Do not log the token.
- Do not include the token in generated documents, public prompts, issue descriptions, or screenshots.
- If a token is exposed, ask the user to revoke it from developer settings and generate a replacement.

## Social OAuth

Use Puppetto-hosted connection links instead of asking for social credentials.

1. Call `puppetto_list_social_posting_providers`.
2. Call `puppetto_get_social_connection_links`.
3. Ask the user to open the relevant URL and complete OAuth.
4. Verify with `puppetto_list_integrations`.
5. Attach connected targets with `puppetto_set_post_targets`.

## LinkedIn Profile Work

Puppetto OAuth stores connection data, not a complete profile scrape. For richer character/profile setup:

1. Use the connected LinkedIn record only as identity and authorization context.
2. If the user wants richer profile extraction, use attended browser/computer use or a user-provided LinkedIn PDF.
3. Show a summary to the user before creating or updating a character.
4. Store confirmed extraction context with `puppetto_resolve_prompt_action` when no direct profile-write tool is available.