# 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 verify 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

Typical flow:

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

The final published docs should include the production MCP server endpoint and authorization issuer once they are confirmed.

---

## 2. OAuth Flow

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 |
| --- | --- | --- | --- |
| 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 |
| Overview analytics read | Retrieve aggregate analytics for an authorized saved search. | Counts, sentiment, reach, interactions, influence, platform, topic, entity, and other available aggregate fields. | Read |
| 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 |
| Future write scopes | Reserved for future actions such as tagging or updating Kommon Poll data. | Depends on the tool. | Write, if introduced |

Grant only the scopes required for the workflow.

If write tools are added later, document them separately and require explicit confirmation before any modifying action.

---

## 5. Verify The Connection

Use a safe read-only prompt:

```text
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:

```text
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:

```text
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. |

Production docs should add exact error messages after final errors are confirmed.