MCP

Connect And Authenticate

Authorize an AI client with OAuth, select the correct team, understand scopes, and troubleshoot connection issues.

Authorize Kommon Poll MCP with OAuth, select the correct team, review scopes, and test that the AI client can access the right saved searches.

Kommon Poll MCP authentication connects an AI client to a user's authorized Kommon Poll data.

Identity and team context are resolved during authorization. The AI model should not supply account IDs, team IDs, access tokens, API keys, or secret headers in prompts.

1. Authentication Architecture

Production MCP endpoint:

https://mcp.kommonpoll.com/mcp

Protected-resource metadata:

https://mcp.kommonpoll.com/.well-known/oauth-protected-resource

Authorization server issuer:

https://kommonpoll.com

Typical flow:

AI client
  -> Kommon Poll authorization flow
  -> user sign-in
  -> team/workspace selection
  -> scope consent
  -> access or refresh token issued to the client
  -> MCP server receives tool calls
  -> Kommon Poll returns authorized data

The MCP endpoint uses bearer tokens in the Authorization header and exposes the protected-resource metadata required by remote MCP clients.

2. OAuth Flow

Kommon Poll OAuth metadata is published at:

https://kommonpoll.com/.well-known/oauth-authorization-server

Key metadata fields:

Field Value
issuer https://kommonpoll.com
authorization_endpoint https://kommonpoll.com/mcpapp/oauth/authorize.php
token_endpoint https://kommonpoll.com/mcpapp/api/oauth/token.php
registration_endpoint https://kommonpoll.com/mcpapp/api/oauth/register.php
revocation_endpoint https://kommonpoll.com/mcpapp/api/oauth/revoke.php
jwks_uri https://kommonpoll.com/.well-known/jwks.json
response_types_supported code
grant_types_supported authorization_code, refresh_token
token_endpoint_auth_methods_supported none, client_secret_basic, client_secret_post
code_challenge_methods_supported S256
client_id_metadata_document_supported true
authorization_response_iss_parameter_supported true
  1. Add Kommon Poll as an MCP server or connector in the AI client.
  2. The client detects that authentication is required.
  3. The client opens the Kommon Poll authorization flow.
  4. Sign in to Kommon Poll.
  5. Select the team or workspace the AI client should access.
  6. Review the requested scopes and permissions.
  7. Grant consent.
  8. Return to the AI client.
  9. Ask the client to list accessible Kommon Poll saved searches.

After authorization, the AI client invokes MCP tools with the user and team identity resolved server-side.

3. Team Selection

Team selection controls which saved searches and projects the AI client can access.

If you belong to multiple teams:

  • Select the team that owns the saved searches you want to analyze.
  • Reconnect or switch the connection if the AI client is using the wrong team.
  • Confirm team behavior in the specific AI client because some clients support multiple connections differently.

If a user later loses access to a Kommon Poll team, MCP tools should no longer return data from that team.

4. Scopes And Permissions

Scopes define what the AI client can do.

Scope category Allows Data exposed Access type
kommonpoll:saved-searches:read List saved searches and project metadata available to the authorized user or team. Saved-search names, identifiers, ownership/team context, and metadata returned by the tool. Read
kommonpoll:overview:read Retrieve aggregate analytics for an authorized saved search. Counts, sentiment, reach, interactions, influence, platform, topic, entity, and other available aggregate fields. Read
kommonpoll:mentions:read Retrieve paginated mention records for an authorized saved search. Mention text, author/source metadata, metrics, sentiment, entities, timestamps, highlights, and classifications where available. Read
kommonpoll:saved-searches:create Create a saved social-listening search in an approved developer or admin workflow. New saved-search title, Boolean keyword, description, owner, and generated identifier. Write
kommonpoll:saved-searches:update Update a saved-search title, Boolean keyword, or description in an approved developer or admin workflow. Updated saved-search metadata and query configuration. Write
offline_access Allow token refresh where the client and authorization flow request it. Refresh-token lifecycle data. Token lifecycle

Grant only the scopes required for the workflow.

Write-capable scopes are not needed for standard read-only analyst workflows. Grant them only to approved clients that intentionally create or update saved searches.

5. Test The Connection

Use a safe read-only prompt:

What Kommon Poll saved searches can you access? Return the name, team or workspace if available, and a one-line description of what each search appears to monitor.

Then test an overview request:

Use the saved search named "Brand Monitoring" and summarize the last 7 days. State the date range, filters, and which Kommon Poll tool you used.

Then test mention retrieval:

Find the 10 most recent negative mentions for the same saved search from the last 7 days. Show source, platform, timestamp, sentiment, and a short reason each mention matters.

6. Token Lifecycle

The AI client may need to re-authenticate when:

  • The OAuth token expires.
  • Access is revoked.
  • The selected team changes.
  • The user's Kommon Poll permissions change.
  • The AI client clears or resets connector credentials.
  • The requested scope is no longer available.

Do not paste access tokens or authorization headers into prompts. Reconnect through the AI client's connector or MCP settings instead.

7. Authentication Troubleshooting

Issue What to check
Authorization page does not open Confirm the AI client supports remote MCP or connectors, and check browser pop-up or admin restrictions.
Login succeeds but connector remains disconnected Reopen the connector settings, retry authorization, and confirm the final consent step completed.
Wrong team selected Disconnect and reconnect using the correct Kommon Poll team, or switch team if the client supports it.
Permission denied Confirm the user has access to the saved search and that the required MCP scope was granted.
Token expired or revoked Reconnect through the AI client.
Saved search not visible Confirm the saved search belongs to the authorized team and is accessible to the signed-in user.
MCP server cannot be reached Confirm the MCP server URL, network access, client transport support, and current service status.

Common unauthenticated endpoint response:

{
  "error": "invalid_token",
  "error_description": "Missing Authorization header"
}