MCP is the agent-provider-neutral way to connect an AI client to SecurityTrackr. You give the client one server URL, it discovers the authorization flow, and a person approves the access it needs. No provider-specific plugin or long-lived API token has to be copied into a prompt. This is the connection guide for any conformant MCP client, whatever agent or host sits in front of it.
One URL for any conformant client
Add this remote MCP endpoint to the client that hosts your agent:
https://app.securitytrackr.com/api/mcpThe server uses Streamable HTTP and JSON-RPC 2.0. It is stateless, has no MCP session to keep alive, and exposes the same observation domain services as the REST API. The client does not need to know which implementation is behind the URL. MCP access is available to organisations on the Pro plan.
The client handles discovery and sign-in
A conformant MCP client can start with only the endpoint URL. When it makes its first unauthenticated request, SecurityTrackr answers with an OAuth resource-metadata challenge. The client follows that metadata to the authorization server and starts an authorization-code flow with PKCE.
- Discovery. The client follows the protected-resource metadata link and learns where authorization lives.
- Client identity. The client presents its Client ID Metadata Document. SecurityTrackr does not expose a Dynamic Client Registration endpoint.
- Authorization. The client uses authorization code plus PKCE with S256, then presents the resulting OAuth access token on each MCP request.
The important part is that the agent provider does not receive a SecurityTrackr password or an API secret. The client handles the redirect, and the person signs in through SecurityTrackr's normal account flow.
Consent is the permission boundary
The consent screen lists the scopes the client requested. Treat that list as a proposal, not a formality. You can remove scopes before approving, and the grant can never contain more than you accepted. The effective authority on every request is the intersection of your SecurityTrackr role and the scopes in the grant.
- Least privilege. A read-only client needs observations.read. Add write or progress scopes only when the workflow genuinely needs them.
- Role changes take effect. A grant never outlives your current role. The server recomputes effective permissions on every request.
- Governance stays human. The grantable scopes do not give an agent a way to accept a risk, delete an observation, or read the audit log.
Twenty-one tools, one domain model
Once connected, the client discovers the complete tool list. The list is not filtered by the current grant, because a missing scope should produce an OAuth step-up challenge rather than make a tool look as if it does not exist.
| Tool | Requires | What it does |
|---|---|---|
| whoami | identity.read | Confirms the organisation, role, and effective permissions. |
| search_observations | observations.read | Searches the register and returns candidate observations. |
| get_observation | observations.read | Reads one observation in full. |
| list_observation_comments | comments.read | Lists comments attached to an observation. |
| add_observation_comment | comments.write | Adds a comment to an observation. |
| update_observation_comment | comments.write | Edits your comment on an observation. |
| delete_observation_comment | comments.write | Deletes a comment from an observation. |
| list_observation_relations | relations.read | Lists relations from an observation's perspective. |
| set_observation_relation | relations.read + relations.write | Creates or replaces the relation between two observations. |
| delete_observation_relation | relations.write | Deletes a relation from an observation. |
| list_observation_evidence | evidence.read | Lists evidence metadata and authenticated download URLs. |
| get_observation_evidence_upload | evidence.write | Returns the authenticated upload handoff; MCP never carries file bytes. |
| delete_observation_evidence | evidence.write | Deletes an evidence file from an observation. |
| prepare_observation_ingest | observations.read, observations.create | Starts the mandatory duplicate-review round. |
| finalize_observation_ingest | observations.read, observations.create | Completes the review and creates the observation. |
| get_observation_ingest | observations.read, observations.create | Reads the state of a review round in progress. |
| update_observation | observations.read + observations.update | Edits fields and recommendation statuses. |
| progress_recommendation | observations.read + observations.progress | Moves a completed recommendation into deployed controls. |
| reassess_observation | observations.read + observations.reassess | Re-runs the AI risk assessment against current controls. |
| get_ai_job | identity.read + the job's original permission | Polls the actor-scoped status of durable AI work. |
| cancel_ai_job | identity.read + the job's original permission | Cancels durable AI work submitted by the same OAuth credential. |
Duplicate review is mandatory
Creating an observation is deliberately a two-call workflow. First, prepare_observation_ingest searches for existing findings that might cover the same concern. The client must dispose of every candidate before finalize_observation_ingest can create the observation. There is no direct create tool that skips that review.
An agent can suggest a disposition, but the server owns the final gate. That keeps duplicate detection and tenant scoping consistent across MCP and REST.
Expiry, attribution, and revocation
OAuth access is deliberately temporary. A grant expires 60 days after approval, and reconnecting starts a new approval. Every connected client is visible under Account → Connected agents, where you can inspect its origin, granted scopes, and status.
Disconnect a client when it no longer needs access or whenever you suspect its environment is compromised. Revocation takes effect on the client's next request. MCP actions are recorded in the audit trail under the authorizing user, with the application recorded alongside them.
What to configure
- Use https://app.securitytrackr.com/api/mcp as the remote MCP server URL.
- Let the client follow the OAuth challenge and complete authorization code plus PKCE.
- Review the requested scopes and remove anything the workflow does not need.
- Keep the client connected to the same SecurityTrackr account that should own its actions.
- Check Account → Connected agents after the first connection and disconnect stale clients.
- Expect a 60-day grant lifetime and plan for a fresh consent flow when access expires.