Connecting MCP Clients to the Poggio MCP Server

Overview

This guide walks enterprise IT administrators through exposing Poggio's capabilities as an MCP server, enabling external AI clients to access your organization's knowledge base and agent capabilities. By connecting external MCP clients to Poggio, you can extend your AI infrastructure beyond the Poggio interface while maintaining centralized knowledge management.

Business impact

Unified AI ecosystem: Provide consistent access to organizational knowledge across multiple AI interfaces
Developer productivity: Enable engineers to access Poggio's capabilities directly via MCP in order to accelerate and enhance agent development
Flexible integration: Support custom applications and workflows that access to deeply researched account intelligence and tailored POVs
Centralized knowledge: Maintain a single source of truth for account intelligence while enabling distributed access

Prerequisites

System requirements

Poggio workspace with administrator privileges
MCP server entitlements enabled for your workspace
External MCP clients (LLM chat applications, custom applications, custom agents, or any other software systems with support for leveraging MCP server capabilities.)
Network connectivity between clients and Poggio's MCP server

Access requirements

Poggio workspace administrator role
Ability to configure external MCP clients
Working knowledge of client-side MCP configuration and network transport

Step 1: Access MCP server settings in Poggio

Navigate to your Poggio workspace
Click on "Settings" in the left sidebar
Select "MCP Server" from the settings menu

Note: If you don't see the MCP Server option, this feature may not be enabled for your workspace. Contact your Poggio administrator or support.

Step 2: Locate the Poggio MCP server URL

At the top of the MCP Server settings page, you'll find the external Poggio MCP server URL. Use the copy button to copy it exactly from the UI.

This URL will be used to configure external MCP clients to connect to your Poggio workspace.

Note: The connection URL does not include a workspace identifier; workspace scoping is implicitly enforced via the generated API token

Step 3: Generate an API token for authentication with the Poggio MCP server

Create your first token

Click "Generate token" to create a new API token
The Create API Token dialog will open

Configure token details

In the Create API Token dialog, provide a descriptive name for the token (e.g., "ACME Slack agent ", "RevOps Control Panel", etc.)

Secure token storage

After creating a token:

Copy the token immediately - it will only be shown once
Store the token securely in your password manager or secure documentation
The token will appear in your token list with partial masking for security

Step 4: Configure your external MCP client

The configuration steps vary by client type:

Open your client application and locate the MCP server settings interface
Add a new MCP server using the URL copied from Poggio settings
Provide the API token as a Bearer token if your client supports it, or in the client’s designated token field
Save the configuration. You may need to restart the client so it can discover tools from the Poggio MCP

Note: Different MCP clients have different configuration formats. Refer to your client’s documentation for how to set a remote HTTP MCP server URL and Bearer token. The Poggio server uses standard HTTPS MCP transport and requires Authorization: Bearer <secure-token> to be present in the request headers.

Example: Custom application integration

For custom applications using MCP client libraries (Python example):

poggio_client_example.py

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://mcp.poggio.io/mcp"  # or copy from settings
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])

Step 5: Test the Connection

Verify client connection

Restart your MCP client application
Check that Poggio appears in the list of connected servers
Verify available tools and capabilities are discovered

Test Poggio capabilities

Try these example interactions to verify the connection:

"What Poggio tools do you have access to?"
"List the available info from Poggio for the <example.com> account"

The MCP inspector is frequently useful at this stage, providing a friendly UI for connecting to remote MCP servers, exploring their capabilities, and invoking tools directly. To launch this development tool locally, run the following (requires Node v22.x+):

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

Paste your MCP auth token directly into the Bearer token input box, then click "Connect"

Step 6: Manage API tokens

Monitor token usage

Review the token list in your MCP Server settings
Check last used dates and activity patterns

Update token settings

Edit: Click the pencil icon to modify token name or expiration
Revoke: Click the trash icon to immediately revoke access

Token security best practices

Use descriptive names to track token purpose
Regularly audit and rotate tokens
Immediately revoke tokens that are no longer needed

Available Poggio capabilities via MCP

When connected to Poggio’s MCP server, external clients can use these tools:

search: Returns a list of account intelligence documents for a given query. The query must begin with a valid domain, e.g. "example.com" or "example.com product strategy".
fetch: Returns the full text and metadata for a specific document ID. Use IDs returned by search. IDs include workspace-level workspace_info and page IDs like account:<company_id>:page:<page_id>.
create_account: Creates a new account in your Poggio workspace using a domain, e.g. create_account(account_domain="example.com"). Intelligence generation begins immediately and becomes available via search / fetch within minutes.

Note: Queries without a leading valid domain will result in an error.

Tool Reference

search

Parameters: query (string). Must start with a valid domain (e.g., "example.com"). Optional free text can follow the domain.
Returns: List of Item objects with fields:
- id (string)
- title (string)
- text (string snippet)
- url (string)

Example result:

[
  {
    "id": "workspace_info",
    "title": "Information on the selling organization Acme Inc (example.com)",
    "text": "• company_name: Acme Inc\n• domain: example.com ...",
    "url": "https://app.poggio.io/<workspace>/..."
  },
  {
    "id": "account:COMPANY_ID:page:PAGE_ID",
    "title": "Market Overview",
    "text": "...markdown snippet...",
    "url": "https://app.poggio.io/<workspace>/accounts/COMPANY_ID/example-com/PAGE_ID"
  }
]

Errors: bad request if the query lacks a valid leading domain; not found if no account exists for the domain.

fetch

Parameters: id (string). Use an id returned by search. Accepted formats include workspace_info and account:<company_id>:page:<page_id>.
Returns: ItemWithMetadata with fields:
- id
- title
- text (full markdown)
- url
- metadata

Example result:

{
  "id": "account:COMPANY_ID:page:PAGE_ID",
  "title": "Market Overview",
  "text": "# Market Overview\n...full markdown content...",
  "url": "https://app.poggio.io/<workspace>/accounts/COMPANY_ID/example-com/PAGE_ID",
  "metadata": null
}

Errors: bad request for malformed IDs; not found if the page or workspace item is unavailable.

create_account

Parameters: account_domain (string). Example: "example.com".
Returns: Object containing:
- id (account id)
- org_id
- domain

Example result:

{
  "id": "ACCOUNT_ID",
  "org_id": "WORKSPACE_ID",
  "domain": "example.com"
}

Note: Triggers deep research for the domain; resulting resources are generally available via search / fetch within minutes.

Security Best Practices

Token management

Generate separate tokens for each client or use case
Use descriptive names to track token purposes
Implement token rotation policies aligned with your security requirements

Access control

Limit MCP server access to authorized clients only
Monitor token usage patterns for unusual activity
Implement network-level restrictions where possible
Regular security audits of client configurations

Data protection

Understand that MCP clients will have access to workspace data
Ensure client applications meet your organization's security standards
Implement appropriate data handling policies for external clients
Monitor data access patterns and usage

Troubleshooting common issues

Connection failures

Symptom: Client cannot connect to Poggio MCP server
Solution:
- Verify the server URL is correct and accessible
- Check that the API token is valid and not expired
- Confirm network connectivity and firewall settings
- Ensure the MCP Server feature is enabled for your workspace

Authentication Errors

Symptom: "Invalid token" or authentication failures
Solution:
- Verify the API token is copied correctly without extra spaces
- Check that the token has not expired
- Confirm the token has not been revoked
- Generate a new token if necessary

Performance Issues

Symptom: Higher than expected latency or API quota back-pressure from Poggio MCP server
Solution:
- Check network connectivity and latency
- Monitor response codes, paying special attention to 429: Too Many Requests responses.
- Consider implementing caching strategies in client applications, and/or reach out to Poggio support to request higher API request quotas.

Next Steps

After successfully connecting MCP clients to Poggio:

Scale integration: Connect additional client applications and development tools
Custom development: Build custom applications leveraging Poggio's MCP capabilities
Team training: Educate developers on effective use of Poggio via MCP clients

For additional assistance, contact Poggio support or your account manager.

Last updated 2 days ago