# Connecting to Poggio MCP


Connect to the Poggio MCP server to access account intelligence tools directly in your AI workflow. There are three ways to authenticate, depending on your use case.

## Server URL

```
https://mcp.poggio.io/mcp
```

All methods below use this same endpoint.

---

## OAuth with Dynamic Client Registration

**Best for:** AI desktop clients like Claude Desktop, Cursor, Windsurf, and other MCP-aware applications that support the standard auth flow.

This is the recommended method for end-user clients. Your client handles the entire OAuth handshake automatically — no manual token management required.

### Prerequisites

- Your MCP client supports the [MCP server authorization design](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)
- Your client supports Dynamic Client Registration (DCR)

### Setup

1. Point your client to `https://mcp.poggio.io/mcp`.
2. Upon connecting, you will be redirected to the Poggio app to authorize the new client.

![Authorizing Claude as an MCP client](/docs/images/mcp-authorize-claude.png)

---

## OAuth Client

**Best for:** Custom applications and backend services that need scoped access with token refresh or machine-to-machine credentials.

Create an OAuth client from **[Settings > OAuth Clients](https://poggio.io/app/settings/oauth-clients)** in your Poggio workspace. Two grant types are available:

### Authorization Code with Refresh Token

Use this when your application acts on behalf of a specific user. The standard OAuth2 authorization code flow issues an access token and a refresh token, so your app can maintain long-lived sessions without re-prompting the user.

1. Create an OAuth client in Settings and note the **client ID** and **client secret**.
2. Redirect the user to Poggio's authorization endpoint.
3. Exchange the authorization code for an access token and refresh token via the [token endpoint](/docs/api/oauth/token).
4. Use the access token as a Bearer token in MCP requests. Refresh it when it expires.

### Client Credentials

Use this for server-to-server integrations where no user interaction is involved. The client authenticates directly with its own credentials.

1. Create an OAuth client in Settings with the **client credentials** grant type.
2. Request an access token directly from the [token endpoint](/docs/api/oauth/token) using your client ID and secret.
3. Use the access token as a Bearer token in MCP requests.

---

## Bearer Token

**Best for:** Quick prototyping, simple scripts, and integrations where OAuth is unnecessary overhead.

Generate an API token from **[Settings > MCP Server](https://poggio.io/app/settings/mcp-server)** in your Poggio workspace.

1. Click **"Generate token"** and provide a descriptive name.
2. Copy the token immediately — it is only displayed once.
3. Pass the token as a Bearer token in your client's request headers.

```python title="example.py"
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://mcp.poggio.io/mcp"
headers = {"Authorization": "Bearer YOUR_API_TOKEN_HERE"}

async with streamablehttp_client(url=url, headers=headers) as (r, w, _):
    async with ClientSession(read_stream=r, write_stream=w) as session:
        await session.initialize()
        tools = await session.list_tools()
        print([t.name for t in tools.tools])
```

> **Note:** The connection URL does not include a workspace identifier — workspace scoping is enforced via the token.

---

## Testing the Connection

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a friendly UI for connecting to remote MCP servers, exploring capabilities, and invoking tools directly. To launch it locally (requires Node v22+):

```bash
npx @modelcontextprotocol/inspector \
  --transport=http \
  --server-url=https://mcp.poggio.io/mcp
```

Paste your Bearer token or OAuth access token into the token input, then click **Connect**.

## Security Best Practices

- Generate separate credentials for each client or use case
- Use descriptive names to track their purpose
- Rotate tokens regularly and revoke any that are no longer needed
- Monitor access patterns for unusual activity
- Ensure client applications meet your organization's security standards

## Troubleshooting

### Connection failures

- Verify the server URL is correct and accessible
- Check that credentials are valid and not expired
- Confirm network connectivity and firewall settings
- Ensure MCP Server is enabled for your workspace

### Authentication errors

- Verify tokens are copied correctly without extra whitespace
- Check that the token or OAuth client has not been revoked
- For OAuth clients, confirm the grant type matches your flow

### Performance issues

- Monitor response codes, especially `429 Too Many Requests`
- Consider caching strategies in client applications
- Contact [Poggio support](mailto:support@poggio.io) to request higher API request quotas

For additional assistance, contact [support@poggio.io](mailto:support@poggio.io) or your account manager.