How do you give an AI agent read-only Search Console access?
An AI agent should measure in Google Search Console and change nothing. What the service account, OAuth scope, ACCESS.md and a guard rail each contribute.
An SEO agent can fetch a page itself and check its title, canonical and hreflang. What Google did with the same address is invisible from outside: whether it is indexed, which canonical Google picked instead, and which queries brought people there. Google Search Console holds those answers, and whoever opens it to an agent wants a promise to go with it. Measuring is the whole job, and the property should look the same afterwards.
The example in this post is an agent called SEO-Audit that looks at the property sc-domain:example.com once a day. SEO-Audit has to find out why https://example.com/blog/agents is missing from the index. Submitting a sitemap is a step it is meant to leave alone.
Access is a service account in Google Cloud
A normal OAuth flow assumes somebody clicks "Allow" in a browser. An agent has no browser, and at three in the morning nobody is there to click. For that reason the Search Console plugin in the covey plugin pack uses a Google service account, which authenticates as itself.
The plugin's setup text lists three steps in Google Cloud: enable the "Google Search Console API", create a service account with no project role, and download a key for it as JSON. Step four happens in Search Console itself, where the service account's mail address is added as a user of the property under Settings, Users and permissions. According to the setup text, skipping it gets you an empty list from the API, with no error.
In covey the whole key file goes into the secret searchconsole_token and the property into searchconsole_url. When the connection is tested, the plugin calls list_sites, so one call checks both the key and the grant. If it finds no property, it names the service account's mail address and the place where the grant is missing.
Read actions ask Google for the read-only scope
Five actions exist in the plugin, and four of them read: list_sites, search_analytics, inspect_url and sitemaps. The fifth, submit_sitemap, tells Google about a sitemap and is the only one that changes anything on the property.
Google offers two OAuth scopes for this, webmasters.readonly to view and webmasters to view and manage. In Google's own description of the API, submitting a sitemap requires the wide scope, while the queries also work with the read-only one.
Scope is chosen per action. Every read goes through a function that requests an access token for webmasters.readonly only, and submit_sitemap alone goes through a second function with the wide scope. For SEO-Audit that means a call to inspect_url on https://example.com/blog/agents runs with a token Google will not accept a sitemap from.
The entry scope: read shortens the description
SEO-Audit's ACCESS.md lists the system with a scope: system: searchconsole scope: read. The obvious assumption is that this entry already prevents writing, and the target systems overview in the covey documentation suggests the same.
In the source the entry does less. With scope: read the plugin drops the section about submit_sitemap from the description the agent reads on every turn. covey checks an action against ACCESS.md only for plugins that name a scope for each action. None is named in the Search Console plugin, so for it the shortened description is all the entry does. If SEO-Audit calls submit_sitemap anyway, covey does not refuse it on the scope, and the plugin requests the wide scope with the same key.
Blocking it takes a guard rail of the type "Action forbidden" on the pattern searchconsole:submit_sitemap. The plugin reports every action to covey under a name of this form, so the rule hits exactly that one action and leaves the four reads alone. Scoping the rule to a single agent is possible. It applies in the control plane before the plugin requests a token, and SEO-Audit gets the reason for the refusal back.
The cost is a key that can request both scopes
The read-only scope is a property of the individual access token. Behind it, the JSON key is still a private key that can request the wide scope too. Whether Google then accepts a submitted sitemap depends on the permission the service account holds on the property. The setup text names "Full" or "Restricted" for that and says either is enough for reading.
To allow writing on purpose, you enter scope: read,write and create no guard rail. Even then the plugin only accepts sitemaps whose address belongs to the property the action works on (without site_url, the configured one), for sc-domain:example.com that means example.com and its subdomains. The plugin has no action that removes a sitemap, so anything it writes there is an addition.
For SEO-Audit the promise therefore sits in three places. The permission on the property decides what Google lets the service account do at all. The per-action scope keeps the reads on webmasters.readonly. The guard rail on searchconsole:submit_sitemap blocks the one write action for this agent.